@openclaw/fs-safe 0.15.0 → 0.16.0

package/dist/archive-tar-wasm.js

@@ -1,6 +1,7 @@
 import { classifyArchiveParserError } from "./archive-parser-errors.js";
 import { readFileSync } from "node:fs";
 import { Transform } from "node:stream";
+import { setImmediate } from "node:timers/promises";
 import { ArchiveFormatError } from "./archive-errors.js";
 // Node exposes WebAssembly without DOM globals; keep the private ABI types local.
 const wasm = globalThis.WebAssembly;
@@ -24,17 +25,14 @@ function parserError(message) {
         return mapped;
     return new ArchiveFormatError(message.replace(/^archive-header-invalid:/, "invalid TAR header:"));
 }
-/** Backpressure-aware transport only; all TAR semantics live in the Rust core. */
-export class TarParserStream extends Transform {
-    onMember;
+/** One bounded memory domain owns both admission and decompression. Its owner
+ * must join the decoder and parser before disposing this shared instance. */
+export class TarWasmSession {
     abi;
-    constructor(limits, onMember) {
-        super();
-        this.onMember = onMember;
+    constructor(limits) {
         this.abi = instance();
         if (this.abi.init(limits.maxEntries, limits.maxMetaEntryBytes, limits.maxDecodedBytes, limits.maxManifestBytes, Number(process.platform === "win32")) !== 0) {
-            this.abi.dispose();
-            this.abi = undefined;
+            this.dispose();
             throw new RangeError("invalid TAR parser limits");
         }
     }
@@ -50,28 +48,133 @@ export class TarParserStream extends Transform {
         const abi = this.abi;
         return utf8Decoder.decode(this.bytes(abi.text_ptr(), abi.text_len()));
     }
-    _transform(chunk, _encoding, callback) {
-        try {
-            const abi = this.abi;
-            for (let offset = 0; offset < chunk.length; offset += 65536) {
-                const length = Math.min(65536, chunk.length - offset);
-                this.bytes(abi.input_ptr(), length).set(chunk.subarray(offset, offset + length));
-                // A member event can stop before the end of this already-copied inbox.
-                for (let consumed = 0; consumed < length;) {
-                    const used = abi.push(consumed, length - consumed);
-                    if (used < 0)
-                        throw parserError(this.text());
-                    if (used === 0 || used > length - consumed)
-                        throw new ArchiveFormatError("TAR WASM made no progress");
-                    consumed += used;
-                    const type = abi.member_type();
-                    if (type >= 0)
-                        this.onMember?.({
-                            path: this.text(), type: types.get(type) ?? "Unsupported", size: abi.member_size(),
-                            mode: abi.member_mode(), offset: abi.member_offset(),
-                        });
+    parse(chunk, onMember) {
+        const abi = this.abi;
+        for (let offset = 0; offset < chunk.length; offset += 65536) {
+            const length = Math.min(65536, chunk.length - offset);
+            this.bytes(abi.input_ptr(), length).set(chunk.subarray(offset, offset + length));
+            // A member event can stop before the end of this already-copied inbox.
+            for (let consumed = 0; consumed < length;) {
+                const used = abi.push(consumed, length - consumed);
+                if (used < 0)
+                    throw parserError(this.text());
+                if (used === 0 || used > length - consumed)
+                    throw new ArchiveFormatError("TAR WASM made no progress");
+                consumed += used;
+                const type = abi.member_type();
+                if (type >= 0)
+                    onMember?.({
+                        path: this.text(), type: types.get(type) ?? "Unsupported", size: abi.member_size(),
+                        mode: abi.member_mode(), offset: abi.member_offset(),
+                    });
+            }
+        }
+    }
+    finish() {
+        if (this.abi.finish() !== 0)
+            throw parserError(this.text());
+    }
+    codecError() {
+        const abi = this.abi;
+        return new ArchiveFormatError(utf8Decoder.decode(this.bytes(abi.codec_error_ptr(), abi.codec_error_len())));
+    }
+    async *decode(source, kind, signal) {
+        const abi = this.abi;
+        signal?.throwIfAborted();
+        if (abi.codec_init(kind === "tar-bzip2" ? 1 : 2) !== 0)
+            throw this.codecError();
+        let work = 0;
+        let calls = 0;
+        let unconsumedBoundary = false;
+        const step = (input) => {
+            signal?.throwIfAborted();
+            this.bytes(abi.codec_input_ptr(), input.length).set(input);
+            const result = abi.codec_push(input.length);
+            if (result < 0)
+                throw this.codecError();
+            const consumed = abi.codec_consumed(), produced = abi.codec_produced();
+            if (!Number.isInteger(consumed) || consumed < 0 || consumed > input.length ||
+                !Number.isInteger(produced) || produced < 0 || produced > 65536 ||
+                (result !== 0 && result !== 1) ||
+                (input.length > 0 && consumed === 0 && produced === 0 && (result !== 1 || unconsumedBoundary))) {
+                throw new ArchiveFormatError("compressed TAR WASM made no progress");
+            }
+            if (input.length > 0)
+                unconsumedBoundary = consumed === 0 && produced === 0;
+            work += consumed + produced;
+            calls++;
+            // The parser can grow this same memory, and the next codec call reuses it.
+            return { consumed, output: produced ? Buffer.from(this.bytes(abi.codec_output_ptr(), produced)) : undefined };
+        };
+        const empty = Buffer.alloc(0);
+        // Yield even for output-free skippable frames and arbitrarily small members.
+        const yieldIfNeeded = async () => {
+            if (work >= 256 * 1024 || calls >= 32) {
+                work = 0;
+                calls = 0;
+                await setImmediate(undefined, { signal });
+            }
+            signal?.throwIfAborted();
+        };
+        for await (const chunk of source) {
+            for (let offset = 0; offset < chunk.length;) {
+                const { consumed, output } = step(chunk.subarray(offset, offset + 65536));
+                offset += consumed;
+                if (output)
+                    yield output;
+                await yieldIfNeeded();
+                // A full output window can leave more decoded bytes with no new input.
+                if (output) {
+                    for (;;) {
+                        const drained = step(empty);
+                        if (drained.output)
+                            yield drained.output;
+                        await yieldIfNeeded();
+                        if (!drained.output)
+                            break;
+                    }
                 }
             }
+        }
+        // Physical EOF, rather than a selected range or TAR EOF, ends the decoder.
+        for (;;) {
+            const drained = step(empty);
+            if (drained.output)
+                yield drained.output;
+            await yieldIfNeeded();
+            if (!drained.output)
+                break;
+        }
+        if (abi.codec_finish() !== 0)
+            throw this.codecError();
+    }
+    dispose() {
+        const abi = this.abi;
+        this.abi = undefined;
+        if (abi) {
+            try {
+                abi.codec_dispose();
+            }
+            finally {
+                abi.dispose();
+            }
+        }
+    }
+}
+/** Backpressure-aware transport only; all TAR semantics live in the Rust core. */
+export class TarParserStream extends Transform {
+    onMember;
+    session;
+    ownsSession;
+    constructor(limits, onMember, session) {
+        super();
+        this.onMember = onMember;
+        this.session = session ?? new TarWasmSession(limits);
+        this.ownsSession = session === undefined;
+    }
+    _transform(chunk, _encoding, callback) {
+        try {
+            this.session.parse(chunk, this.onMember);
             callback(null, chunk);
         }
         catch (error) {
@@ -80,8 +183,7 @@ export class TarParserStream extends Transform {
     }
     _flush(callback) {
         try {
-            if (this.abi.finish() !== 0)
-                throw parserError(this.text());
+            this.session.finish();
             callback();
         }
         catch (error) {
@@ -90,14 +192,12 @@ export class TarParserStream extends Transform {
     }
     _destroy(error, callback) {
         try {
-            this.abi?.dispose();
+            if (this.ownsSession)
+                this.session.dispose();
         }
         catch (cause) {
             error ??= cause instanceof Error ? cause : new Error(String(cause));
         }
-        finally {
-            this.abi = undefined;
-        }
         callback(error);
     }
 }

package/dist/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAIlE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AAiNpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDjF"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAIlE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AAiNpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgDjF"}

package/dist/archive.js

@@ -9,7 +9,7 @@ import { pipeline } from "node:stream/promises";
 import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 import { createPipelineTimeoutError, waitForDeadline, withExtractionDeadline, } from "./archive-deadline.js";
 import { assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, createExtractBudgetTransform, resolveExtractLimits, resolveTarMeterLimits, } from "./archive-limits.js";
-import { assertPortableArchiveKind, resolveArchiveKind } from "./archive-kind.js";
+import { resolveArchiveKind } from "./archive-kind.js";
 import { prepareArchiveDestinationGuard, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
 import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
 import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
@@ -230,8 +230,7 @@ export async function extractArchive(params) {
         await withExtractionDeadline(params.timeoutMs, label, async (deadline) => extractNativeArchive({ ...options, binding: native, kind, tarLimits, deadline }));
         return;
     }
-    assertPortableArchiveKind(kind);
-    if (kind === "tar") {
+    if (kind !== "zip") {
         await withExtractionDeadline(params.timeoutMs, label, async (deadline) => {
             const stagedArchive = await stageArchiveFileForExtraction({
                 archivePath: options.archivePath,
@@ -239,7 +238,7 @@ export async function extractArchive(params) {
                 deadline,
             });
             try {
-                await extractWasmTar({ archivePath: stagedArchive.path, options, limits, tarLimits, deadline });
+                await extractWasmTar({ archivePath: stagedArchive.path, kind, options, limits, tarLimits, deadline });
             }
             finally {
                 await stagedArchive.cleanup();
@@ -252,7 +251,7 @@ export async function extractArchive(params) {
 async function extractWasmTar(params) {
     const { options, deadline, tarLimits } = params;
     const manifest = [];
-    await inspectTar({ archivePath: params.archivePath, limits: tarLimits, signal: deadline.signal,
+    await inspectTar({ archivePath: params.archivePath, kind: params.kind, limits: tarLimits, signal: deadline.signal,
         onMember: (entry) => { manifest.push(entry); } });
     deadline.check();
     const destinationGuard = await prepareArchiveDestinationGuard(options.destDir);
@@ -265,7 +264,7 @@ async function extractWasmTar(params) {
                 const planned = planEntry(entry);
                 return planned ? [{ ...entry, ...planned }] : [];
             });
-            await replayTar({ archivePath: params.archivePath, limits: tarLimits, signal: deadline.signal, members: accepted,
+            await replayTar({ archivePath: params.archivePath, kind: params.kind, limits: tarLimits, signal: deadline.signal, members: accepted,
                 async consume(member, payload) {
                     deadline.check();
                     await preparePrivateArchiveOutputPath({ destinationDir: stagingDir, destinationRealDir: stagingDir,

package/dist/clone-metadata.d.ts

@@ -13,6 +13,7 @@ export type CloneFileMetadata = {
     cloneId: bigint;
 };
 /** Batched APFS metadata snapshots; absent on unsupported files or filesystems.
+ * On macOS, these snapshots require the native helper.
  * These are point-in-time facts, not authorization or a guarantee against later edits.
  */
 export declare function readCloneFileMetadata(files: readonly string[]): Promise<(CloneFileMetadata | undefined)[]>;

package/dist/clone-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clone-metadata.d.ts","sourceRoot":"","sources":["../src/clone-metadata.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,OAAO,CAAC,CAAC,iBAAiB,GAAG,SAAS,CAAC,EAAE,CAAC,CA4B5C"}
+{"version":3,"file":"clone-metadata.d.ts","sourceRoot":"","sources":["../src/clone-metadata.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,OAAO,CAAC,CAAC,iBAAiB,GAAG,SAAS,CAAC,EAAE,CAAC,CA8B5C"}

package/dist/clone-metadata.js

@@ -1,11 +1,15 @@
 import { assertAbsolutePathInput } from "./absolute-path.js";
-import { requireNativeBinding } from "./native.js";
+import { getNativeBinding, requireNativeBinding } from "./native.js";
 /** Batched APFS metadata snapshots; absent on unsupported files or filesystems.
+ * On macOS, these snapshots require the native helper.
  * These are point-in-time facts, not authorization or a guarantee against later edits.
  */
 export async function readCloneFileMetadata(files) {
     const paths = files.map(assertAbsolutePathInput);
-    const results = await requireNativeBinding().readCloneFileMetadata(paths);
+    const native = process.platform === "darwin" ? requireNativeBinding() : getNativeBinding();
+    if (!native)
+        return paths.map(() => undefined);
+    const results = await native.readCloneFileMetadata(paths);
     return results.map((result) => {
         if (!result ||
             result.length !== 100 ||

package/dist/create-directory.d.ts

@@ -0,0 +1,20 @@
+import { type BigIntStats } from "node:fs";
+import { type CreationPermissions } from "./creation-permissions.js";
+import { type CreationParentIdentity } from "./creation-path.js";
+export type CreateDirectoryOptions = CreationPermissions & {
+    assertBeforeMutation?: () => void;
+};
+export type CreationAdmission = {
+    expectedParentIdentity?: CreationParentIdentity;
+};
+export type CreationDirectoryReceipt = {
+    stat: BigIntStats;
+    windowsIdentity?: string;
+};
+export declare function createDirectory(targetPath: string, options?: CreateDirectoryOptions): Promise<void>;
+export declare function createDirectoryWithAdmission(targetPath: string, options?: CreateDirectoryOptions, admission?: CreationAdmission): Promise<void>;
+export declare function createDirectoryWithReceipt(targetPath: string, options?: CreateDirectoryOptions, admission?: CreationAdmission): Promise<CreationDirectoryReceipt>;
+export declare function createDirectorySync(targetPath: string, options?: CreateDirectoryOptions): void;
+export declare function createDirectorySyncWithAdmission(targetPath: string, options?: CreateDirectoryOptions, admission?: CreationAdmission): void;
+export declare function createDirectoryWithReceiptSync(targetPath: string, options?: CreateDirectoryOptions, admission?: CreationAdmission): CreationDirectoryReceipt;
+//# sourceMappingURL=create-directory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-directory.d.ts","sourceRoot":"","sources":["../src/create-directory.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAMnD,OAAO,EAML,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAA0C,KAAK,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AASzG,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,GAAG;IAAE,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC;AACjG,MAAM,MAAM,iBAAiB,GAAG;IAAE,sBAAsB,CAAC,EAAE,sBAAsB,CAAA;CAAE,CAAC;AACpF,MAAM,MAAM,wBAAwB,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAwBvF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,EACpC,SAAS,GAAE,iBAAsB,GAChC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,0BAA0B,CAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,EACpC,SAAS,GAAE,iBAAsB,GAChC,OAAO,CAAC,wBAAwB,CAAC,CAmCnC;AAED,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,IAAI,CAEN;AAED,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,EACpC,SAAS,GAAE,iBAAsB,GAChC,IAAI,CAEN;AAED,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,EACpC,SAAS,GAAE,iBAAsB,GAChC,wBAAwB,CAmC1B"}

package/dist/create-directory.js

@@ -0,0 +1,130 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertPrivateDirectory, assertPrivateDirectorySync, inspectCreationDirectory, inspectCreationDirectorySync, resolveCreationPermissions, } from "./creation-permissions.js";
+import { creationCollision, prepareCreationPath } from "./creation-path.js";
+import { createPrivateWindowsDirectoryCommand, createPrivateWindowsDirectoryCommandSync, } from "./windows-security-command.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { assertDarwinCreationDirectoryAcl, assertDarwinPrivateDirectoryMode } from "./creation-darwin.js";
+function directoryAdoptionFailure(error, target, windowsIdentity) {
+    return new FsSafeError("helper-failed", "created directory admission failed", {
+        cause: error,
+        details: {
+            publication: { status: "published" }, path: target, cleanup: "preserved",
+            ...(windowsIdentity === undefined ? {} : { windowsIdentity }),
+        },
+    });
+}
+function privateDirectoryBackend() {
+    const binding = getNativeBinding();
+    if (typeof binding?.createPrivateDirectoryWithParentIdentity === "function") {
+        return binding.createPrivateDirectoryWithParentIdentity.bind(binding);
+    }
+    if (getFsSafeNativeConfig().mode === "require") {
+        throw new FsSafeError("helper-unavailable", "private directory creation requires an up-to-date native parent identity capability");
+    }
+    warnNativeFallback("windows-private-directory", "Private Windows directory creation uses a slower built-in system command.");
+    return undefined;
+}
+export async function createDirectory(targetPath, options = {}) {
+    await createDirectoryWithAdmission(targetPath, options, {});
+}
+export async function createDirectoryWithAdmission(targetPath, options = {}, admission = {}) {
+    await createDirectoryWithReceipt(targetPath, options, admission);
+}
+export async function createDirectoryWithReceipt(targetPath, options = {}, admission = {}) {
+    const permissions = resolveCreationPermissions(options, true);
+    const assertion = options.assertBeforeMutation;
+    const selected = prepareCreationPath(targetPath, admission.expectedParentIdentity);
+    const backend = permissions.private && process.platform === "win32" ? privateDirectoryBackend() : undefined;
+    const parentIdentity = permissions.private && process.platform === "win32"
+        ? await inspectCreationDirectory(selected.parent.dir, false) : undefined;
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, "directory");
+    assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+    selected.assertParent();
+    if (permissions.private)
+        assertDarwinPrivateDirectoryMode(permissions.mode);
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, "directory");
+    let created = false;
+    let windowsIdentity;
+    try {
+        if (parentIdentity !== undefined) {
+            const receipt = backend
+                ? backend(selected.target, parentIdentity)
+                : await createPrivateWindowsDirectoryCommand(selected.target, parentIdentity);
+            created = true;
+            windowsIdentity = receipt.identity;
+            if ((await inspectCreationDirectory(selected.target, true)) !== receipt.identity) {
+                throw new FsSafeError("path-mismatch", "created private directory changed before adoption");
+            }
+        }
+        else {
+            await fs.mkdir(selected.target, { mode: permissions.mode });
+            created = true;
+            if (permissions.private)
+                await assertPrivateDirectory(selected.target);
+        }
+        selected.assertParent();
+        return { stat: inspectDirectoryIdentitySync(selected.target), windowsIdentity };
+    }
+    catch (error) {
+        if (created)
+            throw directoryAdoptionFailure(error, selected.target, windowsIdentity);
+        throw creationCollision(error);
+    }
+}
+export function createDirectorySync(targetPath, options = {}) {
+    createDirectoryWithReceiptSync(targetPath, options, {});
+}
+export function createDirectorySyncWithAdmission(targetPath, options = {}, admission = {}) {
+    createDirectoryWithReceiptSync(targetPath, options, admission);
+}
+export function createDirectoryWithReceiptSync(targetPath, options = {}, admission = {}) {
+    const permissions = resolveCreationPermissions(options, true);
+    const assertion = options.assertBeforeMutation;
+    const selected = prepareCreationPath(targetPath, admission.expectedParentIdentity);
+    const backend = permissions.private && process.platform === "win32" ? privateDirectoryBackend() : undefined;
+    const parentIdentity = permissions.private && process.platform === "win32"
+        ? inspectCreationDirectorySync(selected.parent.dir, false) : undefined;
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, "directory");
+    assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+    selected.assertParent();
+    if (permissions.private)
+        assertDarwinPrivateDirectoryMode(permissions.mode);
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, "directory");
+    let created = false;
+    let windowsIdentity;
+    try {
+        if (parentIdentity !== undefined) {
+            const receipt = backend
+                ? backend(selected.target, parentIdentity)
+                : createPrivateWindowsDirectoryCommandSync(selected.target, parentIdentity);
+            created = true;
+            windowsIdentity = receipt.identity;
+            if (inspectCreationDirectorySync(selected.target, true) !== receipt.identity) {
+                throw new FsSafeError("path-mismatch", "created private directory changed before adoption");
+            }
+        }
+        else {
+            fsSync.mkdirSync(selected.target, { mode: permissions.mode });
+            created = true;
+            if (permissions.private)
+                assertPrivateDirectorySync(selected.target);
+        }
+        selected.assertParent();
+        return { stat: inspectDirectoryIdentitySync(selected.target), windowsIdentity };
+    }
+    catch (error) {
+        if (created)
+            throw directoryAdoptionFailure(error, selected.target, windowsIdentity);
+        throw creationCollision(error);
+    }
+}

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

@@ -0,0 +1,7 @@
+import { type FileHandle } from "node:fs/promises";
+import { type CreationPath } from "./creation-path.js";
+export declare function createPrivateWindowsFileHandle(selected: CreationPath, options: {
+    mode: number;
+    assertBeforeMutation?: () => void;
+}): Promise<FileHandle>;
+//# sourceMappingURL=create-file-async.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-file-async.d.ts","sourceRoot":"","sources":["../src/create-file-async.ts"],"names":[],"mappings":"AAEA,OAAW,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAevD,OAAO,EAAmD,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKxG,wBAAsB,8BAA8B,CAClD,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GAC3D,OAAO,CAAC,UAAU,CAAC,CA0FrB"}

package/dist/create-file-async.js

@@ -0,0 +1,121 @@
+import { randomUUID } from "node:crypto";
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import path from "node:path";
+import { createDirectoryWithReceipt } from "./create-directory.js";
+import { assertDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertCreationFile, creationPublicationAfterFailure, privateFileSettlementFailure, rethrowPrivateStageCreationFailure, removeRecordedCreationFile, } from "./creation-file-state.js";
+import { inspectCreationDirectory, protectCreatedFile, verifyCreatedFile } from "./creation-permissions.js";
+import { creationCollision, removeCreationDirectoryAsync } from "./creation-path.js";
+import { handoffCreatedFile } from "./private-producer-handoff.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { hasUnsettledWindowsSecurityCommand } from "./windows-security-command.js";
+export async function createPrivateWindowsFileHandle(selected, options) {
+    const assertion = options.assertBeforeMutation;
+    const existing = await fs.lstat(selected.target).catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+        return undefined;
+    });
+    selected.assertParent();
+    if (existing)
+        throw new FsSafeError("already-exists", "creation target already exists");
+    const parentIdentity = await inspectCreationDirectory(selected.parent.dir, false);
+    selected.assertParent();
+    const stageDirectory = path.join(selected.parent.dir, `.fs-safe-create-${randomUUID()}`);
+    let stage;
+    try {
+        stage = await createDirectoryWithReceipt(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 publication = "not-published";
+    try {
+        if (await inspectCreationDirectory(stageDirectory, true) !== stageIdentity) {
+            throw new FsSafeError("path-mismatch", "private staging directory changed before file creation");
+        }
+        assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+        assertStage();
+        file = await fs.open(stagePath, fsSync.constants.O_RDWR | fsSync.constants.O_CREAT |
+            fsSync.constants.O_EXCL | resolveReadOpenFlags(), 0o600);
+        assertStage();
+        identity = assertCreationFile(file.fd, stagePath);
+        assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+        assertStage();
+        assertCreationFile(file.fd, stagePath, identity);
+        const windowsIdentity = await protectCreatedFile(file.fd, stagePath, stageIdentity);
+        assertStage();
+        assertCreationFile(file.fd, stagePath, identity);
+        const source = file;
+        file = undefined;
+        // The handoff consumes the source pin on both success and failure.
+        file = await handoffCreatedFile({
+            source, sourcePath: stagePath, targetPath: selected.target, identity,
+            assertSourceParent: assertStage, assertTargetParent: selected.assertParent,
+            assertBeforeMutation: assertion,
+            verifyDescriptor: (fd, pathname, links) => verifyCreatedFile(fd, pathname, windowsIdentity, pathname === stagePath ? stageIdentity : parentIdentity, links),
+            onPublished: () => { publication = "published"; },
+        });
+        assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+        selected.assertParent();
+        assertCreationFile(file.fd, selected.target, identity);
+        await verifyCreatedFile(file.fd, selected.target, windowsIdentity, parentIdentity);
+        selected.assertParent();
+        assertCreationFile(file.fd, selected.target, identity);
+        await file.chmod(options.mode);
+        await verifyCreatedFile(file.fd, selected.target, windowsIdentity, parentIdentity);
+        selected.assertParent();
+        assertCreationFile(file.fd, selected.target, identity);
+        await removeCreationDirectoryAsync(stageDirectory, stage.stat, selected.assertParent);
+        selected.assertParent();
+        assertCreationFile(file.fd, selected.target, identity);
+        return file;
+    }
+    catch (primary) {
+        publication = creationPublicationAfterFailure(primary, publication);
+        const preserved = publication === "indeterminate" || hasUnsettledWindowsSecurityCommand(primary);
+        const cleanup = [];
+        if (file) {
+            const owned = file;
+            file = undefined;
+            try {
+                await owned.close();
+            }
+            catch (error) {
+                cleanup.push(error);
+            }
+        }
+        if (!preserved) {
+            if (identity) {
+                try {
+                    await removeRecordedCreationFile(stagePath, identity, assertStage);
+                }
+                catch (error) {
+                    cleanup.push(error);
+                }
+            }
+            try {
+                await removeCreationDirectoryAsync(stageDirectory, stage.stat, selected.assertParent);
+            }
+            catch (error) {
+                cleanup.push(error);
+            }
+        }
+        if (publication === "not-published" && cleanup.length === 0 && !preserved)
+            throw creationCollision(primary);
+        throw privateFileSettlementFailure({ primary, cleanup, publication, path: selected.target, stageDirectory, preserved });
+    }
+}

package/dist/create-file.d.ts

@@ -0,0 +1,8 @@
+import { type FileHandle } from "node:fs/promises";
+import { type CreateDirectoryOptions, type CreationAdmission } from "./create-directory.js";
+import { type OwnedFileDescriptorSync } from "./create-owned-file.js";
+export type CreateFileOptions = CreateDirectoryOptions;
+export declare function createFileSync(targetPath: string, options?: CreateFileOptions): OwnedFileDescriptorSync;
+/** Internal async writer; Windows preparation uses the nonblocking stage owner. */
+export declare function createFileHandle(targetPath: string, options?: CreateFileOptions, admission?: CreationAdmission): Promise<FileHandle>;
+//# sourceMappingURL=create-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-file.d.ts","sourceRoot":"","sources":["../src/create-file.ts"],"names":[],"mappings":"AAEA,OAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,EAAkC,KAAK,sBAAsB,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC5H,OAAO,EAAyB,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AA2B7F,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;AA8GvD,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,uBAAuB,CAE3G;AAED,mFAAmF;AACnF,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,iBAAsB,EAC/B,SAAS,GAAE,iBAAsB,GAChC,OAAO,CAAC,UAAU,CAAC,CA+BrB"}