@openclaw/fs-safe 0.15.0 → 0.16.0

package/dist/create-file.js

@@ -0,0 +1,190 @@
+import { randomUUID } from "node:crypto";
+import fs, {} from "node:fs";
+import fsAsync, {} from "node:fs/promises";
+import path from "node:path";
+import { createDirectoryWithReceiptSync } from "./create-directory.js";
+import { ownFileDescriptorSync } from "./create-owned-file.js";
+import { assertDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertPrivateFileCreationAvailable, inspectCreationDirectorySync, protectCreatedFileSync, resolveCreationPermissions, verifyCreatedFileSync, } from "./creation-permissions.js";
+import { creationCollision, prepareCreationPath, removeCreationDirectory } from "./creation-path.js";
+import { handoffCreatedFileSync } from "./private-producer-handoff-sync.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { assertCreationFile, assertPrivateCreationFile, creationPublicationAfterFailure, privateFileSettlementFailure, rethrowPrivateStageCreationFailure, removeRecordedCreationFileSync, } from "./creation-file-state.js";
+import { createPrivateWindowsFileHandle } from "./create-file-async.js";
+import { assertDarwinCreationDirectoryAcl } from "./creation-darwin.js";
+function createPrivateWindowsFile(selected, options, mode) {
+    const assertion = options.assertBeforeMutation;
+    if (fs.lstatSync(selected.target, { throwIfNoEntry: false })) {
+        throw new FsSafeError("already-exists", "creation target already exists");
+    }
+    const parentIdentity = inspectCreationDirectorySync(selected.parent.dir, false);
+    selected.assertParent();
+    const stageDirectory = path.join(selected.parent.dir, `.fs-safe-create-${randomUUID()}`);
+    let stage;
+    try {
+        stage = createDirectoryWithReceiptSync(stageDirectory, { private: true, assertBeforeMutation: assertion }, {
+            expectedParentIdentity: selected.parent.stat,
+        });
+    }
+    catch (error) {
+        rethrowPrivateStageCreationFailure(error, selected.target, stageDirectory);
+    }
+    const stageIdentity = stage.windowsIdentity;
+    const stagePath = path.join(stageDirectory, "file");
+    const assertStage = () => {
+        selected.assertParent();
+        assertDirectoryIdentitySync(stageDirectory, stage.stat);
+    };
+    let file;
+    let identity;
+    let windowsIdentity;
+    let publication = "not-published";
+    try {
+        if (inspectCreationDirectorySync(stageDirectory, true) !== stageIdentity) {
+            throw new FsSafeError("path-mismatch", "private staging directory changed before file creation");
+        }
+        assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+        assertStage();
+        file = ownFileDescriptorSync(fs.openSync(stagePath, fs.constants.O_RDWR | fs.constants.O_CREAT |
+            fs.constants.O_EXCL | resolveReadOpenFlags(), 0o600));
+        identity = assertCreationFile(file.fd, stagePath);
+        // The inherited ACL must already be restrictive. This freezes that policy;
+        // the bridge refuses to repair broad access on an exposed file.
+        assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+        assertStage();
+        assertCreationFile(file.fd, stagePath, identity);
+        windowsIdentity = protectCreatedFileSync(file.fd, stagePath, stageIdentity);
+        assertStage();
+        file = handoffCreatedFileSync({
+            source: file, sourcePath: stagePath, targetPath: selected.target, identity,
+            assertSourceParent: assertStage, assertTargetParent: selected.assertParent,
+            assertBeforeMutation: assertion,
+            verifyDescriptor: (fd, pathname, links) => verifyCreatedFileSync(fd, pathname, windowsIdentity, pathname === stagePath ? stageIdentity : parentIdentity, links),
+            onPublished: () => { publication = "published"; },
+        });
+        // Windows may clear the read-only attribute while retiring the stage name.
+        // Finalize it only after the published-name descriptor owns the file.
+        fs.fchmodSync(file.fd, mode);
+        selected.assertParent();
+        identity = assertCreationFile(file.fd, selected.target, identity);
+        verifyCreatedFileSync(file.fd, selected.target, windowsIdentity, parentIdentity);
+        removeCreationDirectory(stageDirectory, stage.stat, selected.assertParent);
+        return file;
+    }
+    catch (primary) {
+        publication = creationPublicationAfterFailure(primary, publication);
+        const cleanup = [];
+        if (file) {
+            try {
+                file.close();
+            }
+            catch (error) {
+                cleanup.push(error);
+            }
+        }
+        if (publication !== "indeterminate") {
+            if (identity) {
+                try {
+                    removeRecordedCreationFileSync(stagePath, identity, assertStage);
+                }
+                catch (error) {
+                    cleanup.push(error);
+                }
+            }
+            try {
+                removeCreationDirectory(stageDirectory, stage.stat, selected.assertParent);
+            }
+            catch (error) {
+                cleanup.push(error);
+            }
+        }
+        if (publication === "not-published" && cleanup.length === 0)
+            throw creationCollision(primary);
+        throw privateFileSettlementFailure({ primary, cleanup, publication, path: selected.target, stageDirectory });
+    }
+}
+function createFileCore(targetPath, options, admission) {
+    const permissions = resolveCreationPermissions(options, false);
+    const assertion = options.assertBeforeMutation;
+    const selected = prepareCreationPath(targetPath, admission.expectedParentIdentity);
+    if (permissions.private && process.platform === "win32") {
+        assertPrivateFileCreationAvailable();
+        return createPrivateWindowsFile(selected, { ...permissions, assertBeforeMutation: assertion }, permissions.mode);
+    }
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, "file");
+    assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+    selected.assertParent();
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, "file");
+    let file;
+    try {
+        file = ownFileDescriptorSync(fs.openSync(selected.target, fs.constants.O_RDWR | fs.constants.O_CREAT |
+            fs.constants.O_EXCL | resolveReadOpenFlags(), permissions.mode ?? 0o666));
+    }
+    catch (error) {
+        throw creationCollision(error);
+    }
+    try {
+        const identity = assertCreationFile(file.fd, selected.target);
+        selected.assertParent();
+        if (permissions.private)
+            assertPrivateCreationFile(identity, file.fd);
+        return file;
+    }
+    catch (primary) {
+        let failure = primary;
+        try {
+            file.close();
+        }
+        catch (closeError) {
+            failure = new AggregateError([primary, closeError], "created file admission and close failed");
+        }
+        throw new FsSafeError("helper-failed", "created file admission failed", {
+            cause: failure, details: { publication: { status: "published" }, path: selected.target, cleanup: "preserved" },
+        });
+    }
+}
+export function createFileSync(targetPath, options = {}) {
+    return createFileCore(targetPath, options, {});
+}
+/** Internal async writer; Windows preparation uses the nonblocking stage owner. */
+export async function createFileHandle(targetPath, options = {}, admission = {}) {
+    const permissions = resolveCreationPermissions(options, false);
+    const assertion = options.assertBeforeMutation;
+    if (process.platform !== "win32" || !permissions.private) {
+        const selected = prepareCreationPath(targetPath, admission.expectedParentIdentity);
+        if (permissions.private)
+            assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, "file");
+        assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+        selected.assertParent();
+        if (permissions.private)
+            assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, "file");
+        const handle = await fsAsync.open(selected.target, fs.constants.O_RDWR | fs.constants.O_CREAT |
+            fs.constants.O_EXCL | resolveReadOpenFlags(), permissions.mode ?? 0o666)
+            .catch(error => { throw creationCollision(error); });
+        try {
+            const identity = assertCreationFile(handle.fd, selected.target);
+            selected.assertParent();
+            if (permissions.private)
+                assertPrivateCreationFile(identity, handle.fd);
+            return handle;
+        }
+        catch (primary) {
+            let failure = primary;
+            try {
+                await handle.close();
+            }
+            catch (closeError) {
+                failure = new AggregateError([primary, closeError], "created file admission and close failed");
+            }
+            throw new FsSafeError("helper-failed", "created file handle admission failed", {
+                cause: failure, details: { publication: { status: "published" }, path: selected.target, cleanup: "preserved" },
+            });
+        }
+    }
+    assertPrivateFileCreationAvailable();
+    return await createPrivateWindowsFileHandle(prepareCreationPath(targetPath, admission.expectedParentIdentity), { mode: permissions.mode, assertBeforeMutation: assertion });
+}

package/dist/create-owned-file.d.ts

@@ -0,0 +1,8 @@
+export type OwnedFileDescriptorSync = {
+    readonly fd: number;
+    close(): void;
+    [Symbol.dispose](): void;
+};
+/** Capture the descriptor's creator-owned closer before it can be reused. */
+export declare function ownFileDescriptorSync(fd: number, closeFd?: (fd: number) => void): OwnedFileDescriptorSync;
+//# sourceMappingURL=create-owned-file.d.ts.map

package/dist/create-owned-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-owned-file.d.ts","sourceRoot":"","sources":["../src/create-owned-file.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,KAAK,IAAI,IAAI,CAAC;IACd,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAmB,GAC3C,uBAAuB,CAYzB"}

package/dist/create-owned-file.js

@@ -0,0 +1,16 @@
+import fs from "node:fs";
+/** Capture the descriptor's creator-owned closer before it can be reused. */
+export function ownFileDescriptorSync(fd, closeFd = fs.closeSync) {
+    let open = true;
+    const owner = {
+        fd,
+        close() {
+            if (!open)
+                return;
+            open = false;
+            closeFd(fd);
+        },
+        [Symbol.dispose]() { owner.close(); },
+    };
+    return Object.freeze(owner);
+}

package/dist/create.d.ts

@@ -0,0 +1,4 @@
+export { createDirectory, createDirectorySync, createDirectoryWithAdmission, createDirectorySyncWithAdmission, type CreateDirectoryOptions, type CreationAdmission, } from "./create-directory.js";
+export { createFileSync, createFileHandle, type CreateFileOptions } from "./create-file.js";
+export type { OwnedFileDescriptorSync } from "./create-owned-file.js";
+//# sourceMappingURL=create.d.ts.map

package/dist/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAAE,mBAAmB,EACpC,4BAA4B,EAAE,gCAAgC,EAC9D,KAAK,sBAAsB,EAAE,KAAK,iBAAiB,GACpD,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC5F,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/create.js

@@ -0,0 +1,2 @@
+export { createDirectory, createDirectorySync, createDirectoryWithAdmission, createDirectorySyncWithAdmission, } from "./create-directory.js";
+export { createFileSync, createFileHandle } from "./create-file.js";

package/dist/creation-darwin.d.ts

@@ -0,0 +1,7 @@
+import { type BigIntStats } from "node:fs";
+export declare function assertDarwinPrivateCreationAvailable(): void;
+export declare function assertDarwinPrivateDirectoryMode(mode: number): void;
+export declare function assertDarwinCreationAcl(fd: number, inheritanceTarget?: "file" | "directory"): void;
+export declare function assertDarwinCreationDirectoryAcl(pathname: string, expected: BigIntStats, inheritanceTarget?: "file" | "directory"): void;
+export declare function privateFileMutationAssertion(fd: number, assertion?: () => void): (() => void) | undefined;
+//# sourceMappingURL=creation-darwin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"creation-darwin.d.ts","sourceRoot":"","sources":["../src/creation-darwin.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAgB/C,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D;AAED,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAInE;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAYlG;AAED,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,WAAW,GAChF,IAAI,CAqBN;AAED,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAMzG"}

package/dist/creation-darwin.js

@@ -0,0 +1,79 @@
+import fs, {} from "node:fs";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { nodeDarwinDirectoryMetadataFlags, nodeDirectorySearchOnlyFlags } from "./directory-mode-node.js";
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { getNativeBinding } from "./native.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+function inspector() {
+    const native = getNativeBinding();
+    if (typeof native?.inspectDarwinAcl !== "function") {
+        throw new FsSafeError("helper-unavailable", "private Darwin creation requires native descriptor ACL inspection");
+    }
+    return native.inspectDarwinAcl.bind(native);
+}
+export function assertDarwinPrivateCreationAvailable() {
+    if (process.platform === "darwin")
+        inspector();
+}
+export function assertDarwinPrivateDirectoryMode(mode) {
+    if (process.platform === "darwin" && ((mode & ~process.umask()) & 0o500) === 0) {
+        throw new FsSafeError("helper-unavailable", "private Darwin directory ACL inspection requires owner read or search permission");
+    }
+}
+export function assertDarwinCreationAcl(fd, inheritanceTarget) {
+    if (process.platform !== "darwin")
+        return;
+    const inspect = inspector();
+    const state = inspect(fd, inheritanceTarget)?.state;
+    if (state === "present") {
+        throw new FsSafeError("insecure-permissions", inheritanceTarget
+            ? "private creation parent has inheritable Darwin ACL entries"
+            : "private creation object has Darwin ACL entries");
+    }
+    if (state !== "absent" && state !== "empty") {
+        throw new FsSafeError("helper-unavailable", "native Darwin ACL inspection returned incomplete facts");
+    }
+}
+export function assertDarwinCreationDirectoryAcl(pathname, expected, inheritanceTarget) {
+    if (process.platform !== "darwin")
+        return;
+    assertDarwinPrivateCreationAvailable();
+    let fd;
+    try {
+        fd = fs.openSync(pathname, nodeDarwinDirectoryMetadataFlags());
+    }
+    catch (error) {
+        if (error.code !== "EACCES")
+            throw error;
+        const search = nodeDirectorySearchOnlyFlags();
+        if (!search)
+            throw error;
+        try {
+            fd = fs.openSync(pathname, search.flags | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+        }
+        catch (cause) {
+            if (cause.code !== "EACCES")
+                throw cause;
+            throw new FsSafeError("helper-unavailable", "private Darwin directory ACL inspection requires owner read or search permission", { cause });
+        }
+    }
+    try {
+        const opened = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }), expected);
+        if (!opened.isDirectory())
+            throw new FsSafeError("path-mismatch", "ACL target is not the admitted directory");
+        assertDarwinCreationAcl(fd, inheritanceTarget);
+        inspectDirectoryIdentitySync(pathname, expected);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function privateFileMutationAssertion(fd, assertion) {
+    if (process.platform !== "darwin")
+        return assertion;
+    return () => {
+        assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+        assertDarwinCreationAcl(fd);
+    };
+}

package/dist/creation-file-state.d.ts

@@ -0,0 +1,19 @@
+import { type BigIntStats } from "node:fs";
+import { FsSafeError } from "./errors.js";
+export type CreationPublicationStatus = "not-published" | "published" | "indeterminate";
+export declare function assertCreationFile(fd: number, pathname: string, expected?: BigIntStats): BigIntStats;
+export declare function assertPrivateCreationFile(stat: BigIntStats, fd: number): void;
+export declare function removeRecordedCreationFileSync(pathname: string, identity: BigIntStats, assertParent: () => void): void;
+export declare function removeRecordedCreationFile(pathname: string, identity: BigIntStats, assertParent: () => void): Promise<void>;
+export declare function creationPublicationAfterFailure(error: unknown, recorded: CreationPublicationStatus): CreationPublicationStatus;
+export declare function hasPreservedCreationArtifacts(error: unknown): boolean;
+export declare function rethrowPrivateStageCreationFailure(error: unknown, path: string, stageDirectory: string): never;
+export declare function privateFileSettlementFailure(params: {
+    primary: unknown;
+    cleanup: readonly unknown[];
+    publication: CreationPublicationStatus;
+    path: string;
+    stageDirectory: string;
+    preserved?: boolean;
+}): FsSafeError;
+//# sourceMappingURL=creation-file-state.d.ts.map

package/dist/creation-file-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creation-file-state.d.ts","sourceRoot":"","sources":["../src/creation-file-state.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM1C,MAAM,MAAM,yBAAyB,GAAG,eAAe,GAAG,WAAW,GAAG,eAAe,CAAC;AAExF,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,WAAW,CAOpG;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAS7E;AAQD,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,IAAI,GAAG,IAAI,CAUtH;AAED,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,IAAI,GAChE,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,yBAAyB,GAClD,yBAAyB,CAO3B;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMrE;AAED,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,KAAK,CAuB9G;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IAC5B,WAAW,EAAE,yBAAyB,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,WAAW,CAUd"}

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