@openclaw/fs-safe 0.5.6 → 0.7.0

package/dist/json-durable-queue.js

@@ -1,9 +1,13 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import path from "node:path";
-import { sameFileIdentity } from "./file-identity.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { syncQueueDirectoryCreation } from "./json-durable-queue-directory.js";
+import { acknowledgeDurableQueueEntry, claimDurableQueueEntry, completeDeliveredQueueEntry, moveDurableQueueEntryToFailed, } from "./json-durable-queue-ownership.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { replaceFileAtomic } from "./replace-file.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
 export const DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES = 16 * 1024 * 1024;
 function getErrnoCode(error) {
     return error && typeof error === "object" && "code" in error
@@ -46,6 +50,7 @@ export function resolveJsonDurableQueueEntryPaths(queueDir, id) {
     return {
         jsonPath: path.join(queueDir, `${id}.json`),
         deliveredPath: path.join(queueDir, `${id}.delivered`),
+        processingPath: path.join(queueDir, `${id}.processing`),
     };
 }
 export async function ensureJsonDurableQueueDirs(params) {
@@ -61,6 +66,7 @@ async function ensureJsonDurableQueueDir(dir, validationRoot) {
     await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
     await assertNoSymlinkDirectorySegments(root, dir, false);
     await chmodQueueDirectory(dir);
+    await syncQueueDirectoryCreation(dir, root.path);
 }
 async function assertJsonDurableQueueDir(dir, validationRoot) {
     const root = validationRoot
@@ -208,35 +214,55 @@ export async function writeJsonDurableQueueEntry(params) {
         content: stringifyJsonDocument(params.entry, null, 2),
         mode: 0o600,
         tempPrefix: params.tempPrefix,
+        syncTempFile: true,
+        syncParentDir: true,
     });
 }
-async function readBoundedUtf8File(params) {
-    const initialStat = await fs.promises.lstat(params.filePath);
-    if (initialStat.isSymbolicLink() || !initialStat.isFile()) {
-        throw new Error("queue entry is not a regular file");
-    }
-    if (initialStat.nlink > 1) {
-        throw new Error("queue entry hardlinks are not allowed");
+async function replaceJsonDurableQueueEntry(params) {
+    await replaceFileAtomic({
+        filePath: params.filePath,
+        content: stringifyJsonDocument(params.entry, null, 2),
+        mode: 0o600,
+        tempPrefix: params.tempPrefix,
+        syncTempFile: true,
+        syncParentDir: true,
+    });
+}
+async function inspectQueueEntry(inspect, maxBytes, expected) {
+    let inspectionFailed = false;
+    try {
+        return await inspectFileIdentity(async () => {
+            try {
+                const stat = await inspect();
+                if (stat.isSymbolicLink() || !stat.isFile()) {
+                    throw new Error("queue entry is not a regular file");
+                }
+                if (stat.nlink > 1n)
+                    throw new Error("queue entry hardlinks are not allowed");
+                if (stat.size > maxBytes)
+                    throw new Error(`queue entry exceeds ${maxBytes} bytes`);
+                return stat;
+            }
+            catch (error) {
+                inspectionFailed = true;
+                throw error;
+            }
+        }, expected);
     }
-    if (initialStat.size > params.maxBytes) {
-        throw new Error(`queue entry exceeds ${params.maxBytes} bytes`);
+    catch (error) {
+        // Translate only the identity helper's rejection, never inspection errors.
+        if (inspectionFailed)
+            throw error;
+        throw new Error("queue entry changed during read", { cause: error });
     }
-    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" && process.platform !== "win32"
-        ? fs.constants.O_NOFOLLOW
-        : 0;
-    const handle = await fs.promises.open(params.filePath, fs.constants.O_RDONLY | noFollow);
+}
+async function readBoundedUtf8File(params) {
+    const inspectPath = () => fs.promises.lstat(params.filePath, { bigint: true });
+    const initialStat = await inspectQueueEntry(inspectPath, params.maxBytes);
+    const handle = await fs.promises.open(params.filePath, resolveReadOpenFlags());
     try {
-        const openedStat = await handle.stat();
-        const pathStat = await fs.promises.lstat(params.filePath);
-        if (!openedStat.isFile() ||
-            pathStat.isSymbolicLink() ||
-            !pathStat.isFile() ||
-            openedStat.nlink > 1 ||
-            pathStat.nlink > 1 ||
-            !sameFileIdentity(initialStat, openedStat) ||
-            !sameFileIdentity(pathStat, openedStat)) {
-            throw new Error("queue entry changed during read");
-        }
+        const openedStat = await inspectQueueEntry(() => handle.stat({ bigint: true }), params.maxBytes, initialStat);
+        await inspectQueueEntry(inspectPath, params.maxBytes, openedStat);
         const chunks = [];
         const scratch = Buffer.allocUnsafe(Math.min(64 * 1024, params.maxBytes + 1));
         let total = 0;
@@ -259,35 +285,26 @@ async function readBoundedUtf8File(params) {
 export async function readJsonDurableQueueEntry(filePath, options = {}) {
     return JSON.parse(await readBoundedUtf8File({
         filePath,
-        maxBytes: options.maxBytes ?? DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES,
+        maxBytes: normalizeMaxBytes(options.maxBytes, {
+            defaultValue: DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES,
+        }),
     }));
 }
 export async function ackJsonDurableQueueEntry(paths) {
-    try {
-        await fs.promises.rename(paths.jsonPath, paths.deliveredPath);
-    }
-    catch (error) {
-        if (getErrnoCode(error) === "ENOENT") {
-            await unlinkBestEffort(paths.deliveredPath);
-            return;
-        }
-        throw error;
-    }
-    await unlinkBestEffort(paths.deliveredPath);
+    await acknowledgeDurableQueueEntry(paths);
 }
 export async function loadJsonDurableQueueEntry(params) {
     try {
-        const stat = await fs.promises.lstat(params.paths.jsonPath);
-        if (!stat.isFile()) {
+        const claimedPath = await claimDurableQueueEntry(params.paths);
+        if (!claimedPath)
             return null;
-        }
-        const raw = await readJsonDurableQueueEntry(params.paths.jsonPath, {
+        const raw = await readJsonDurableQueueEntry(claimedPath, {
             maxBytes: params.maxBytes,
         });
         const result = params.read ? await params.read(raw, params.paths.jsonPath) : { entry: raw };
         if (result.migrated) {
-            await writeJsonDurableQueueEntry({
-                filePath: params.paths.jsonPath,
+            await replaceJsonDurableQueueEntry({
+                filePath: claimedPath,
                 entry: result.entry,
                 tempPrefix: params.tempPrefix,
             });
@@ -315,28 +332,41 @@ export async function loadPendingJsonDurableQueueEntries(options) {
     const now = Date.now();
     for (const file of files) {
         if (file.endsWith(".delivered")) {
-            await unlinkBestEffort(path.join(options.queueDir, file));
+            const id = file.slice(0, -".delivered".length);
+            await completeDeliveredQueueEntry(resolveJsonDurableQueueEntryPaths(options.queueDir, id));
         }
         else if (options.cleanupTmpMaxAgeMs !== undefined && file.endsWith(".tmp")) {
             await unlinkStaleTmpBestEffort(path.join(options.queueDir, file), now, options.cleanupTmpMaxAgeMs);
         }
     }
-    const entries = [];
+    const ids = [];
+    const seenIds = new Set();
     for (const file of files) {
-        if (!file.endsWith(".json")) {
+        const suffix = file.endsWith(".processing")
+            ? ".processing"
+            : file.endsWith(".json")
+                ? ".json"
+                : null;
+        if (!suffix)
             continue;
-        }
-        const filePath = path.join(options.queueDir, file);
+        const id = file.slice(0, -suffix.length);
+        if (seenIds.has(id))
+            continue;
+        seenIds.add(id);
+        ids.push(id);
+    }
+    const entries = [];
+    for (const id of ids) {
         try {
-            const stat = await fs.promises.lstat(filePath);
-            if (!stat.isFile()) {
+            const paths = resolveJsonDurableQueueEntryPaths(options.queueDir, id);
+            const claimedPath = await claimDurableQueueEntry(paths);
+            if (!claimedPath)
                 continue;
-            }
-            const raw = await readJsonDurableQueueEntry(filePath, { maxBytes: options.maxBytes });
-            const result = options.read ? await options.read(raw, filePath) : { entry: raw };
+            const raw = await readJsonDurableQueueEntry(claimedPath, { maxBytes: options.maxBytes });
+            const result = options.read ? await options.read(raw, paths.jsonPath) : { entry: raw };
             if (result.migrated) {
-                await writeJsonDurableQueueEntry({
-                    filePath,
+                await replaceJsonDurableQueueEntry({
+                    filePath: claimedPath,
                     entry: result.entry,
                     tempPrefix: options.tempPrefix,
                 });
@@ -354,5 +384,8 @@ export async function moveJsonDurableQueueEntryToFailed(params) {
     const roots = await queueValidationRoots(params.queueDir, params.failedDir);
     await assertJsonDurableQueueDir(params.queueDir, roots.queueRoot);
     await ensureJsonDurableQueueDir(params.failedDir, roots.failedRoot);
-    await fs.promises.rename(path.join(params.queueDir, `${params.id}.json`), path.join(params.failedDir, `${params.id}.json`));
+    await moveDurableQueueEntryToFailed({
+        paths: resolveJsonDurableQueueEntryPaths(params.queueDir, params.id),
+        failedPath: path.join(params.failedDir, `${params.id}.json`),
+    });
 }

package/dist/json.d.ts.map

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

package/dist/json.js

@@ -3,9 +3,11 @@ import fsSync from "node:fs";
 import path from "node:path";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { readRegularFile, readRegularFileSync, statRegularFile } from "./regular-file.js";
 import { openRootFileSync } from "./root-file.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { writeTextAtomic } from "./text-atomic.js";
 import { sleep } from "./timing.js";
 const READ_RETRY_MAX_ATTEMPTS = 5;
@@ -48,19 +50,35 @@ async function readRegularFileIfExistsWithRetry(filePath, options = {}) {
 }
 const JSON_FILE_MODE = 0o600;
 const JSON_DIR_MODE = 0o700;
-const SUPPORTS_SYNC_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants;
 function getErrorCode(err) {
     return err instanceof Error ? err.code : undefined;
 }
-function trySetSecureMode(pathname) {
+function trySetSecureMode(pathname, expectedIdentity) {
     let fd;
     try {
-        fd = fsSync.openSync(pathname, fsSync.constants.O_RDONLY |
-            (SUPPORTS_SYNC_NOFOLLOW ? fsSync.constants.O_NOFOLLOW : 0));
+        const before = fsSync.lstatSync(pathname, { bigint: true });
+        if (before.isSymbolicLink() ||
+            !before.isFile() ||
+            before.nlink !== 1n ||
+            !sameFileIdentityForCleanup(before, expectedIdentity)) {
+            return;
+        }
+        fd = fsSync.openSync(pathname, resolveReadOpenFlags());
+        const opened = fsSync.fstatSync(fd, { bigint: true });
+        const current = fsSync.lstatSync(pathname, { bigint: true });
+        if (!opened.isFile() ||
+            opened.nlink !== 1n ||
+            current.isSymbolicLink() ||
+            !current.isFile() ||
+            current.nlink !== 1n ||
+            !sameFileIdentityForCleanup(opened, expectedIdentity) ||
+            !sameFileIdentityForCleanup(current, opened)) {
+            return;
+        }
         fsSync.fchmodSync(fd, JSON_FILE_MODE);
     }
     catch {
-        // best-effort on platforms without chmod support
+        // Best-effort mode application never falls back to a mutable pathname.
     }
     finally {
         if (fd !== undefined) {
@@ -129,6 +147,7 @@ function writeTempJsonFile(pathname, payload) {
     try {
         fsSync.writeFileSync(fd, payload, "utf8");
         fsSync.fsyncSync(fd);
+        return fsSync.fstatSync(fd, { bigint: true });
     }
     finally {
         fsSync.closeSync(fd);
@@ -152,10 +171,10 @@ export function writeJsonSync(pathname, data) {
     const payload = `${stringifyJsonDocument(data, null, 2)}\n`;
     fsSync.mkdirSync(path.dirname(targetPath), { recursive: true, mode: JSON_DIR_MODE });
     try {
-        writeTempJsonFile(tmpPath, payload);
-        trySetSecureMode(tmpPath);
+        const tempIdentity = writeTempJsonFile(tmpPath, payload);
+        trySetSecureMode(tmpPath, tempIdentity);
         renameJsonFileWithFallback(tmpPath, targetPath);
-        trySetSecureMode(targetPath);
+        trySetSecureMode(targetPath, tempIdentity);
         trySyncDirectory(targetPath);
     }
     finally {

package/dist/local-roots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-roots.d.ts","sourceRoot":"","sources":["../src/local-roots.ts"],"names":[],"mappings":"AAMA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG,sBAAsB,GAAG;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAqGF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,oBAAoB,GAAG,IAAI,CA6B7B;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA2CtC"}
+{"version":3,"file":"local-roots.d.ts","sourceRoot":"","sources":["../src/local-roots.ts"],"names":[],"mappings":"AAOA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG,sBAAsB,GAAG;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAqGF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,oBAAoB,GAAG,IAAI,CA6B7B;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA4CtC"}

package/dist/local-roots.js

@@ -1,5 +1,6 @@
 import fsSync from "node:fs";
 import path from "node:path";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
 import { expandHomePrefix, resolveUserPath } from "./home-dir.js";
 import { isFileUrl, safeFileURLToPath } from "./local-file-access.js";
@@ -129,6 +130,7 @@ export function resolveLocalPathFromRootsSync(options) {
     return null;
 }
 export async function readLocalFileFromRoots(options) {
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
     const label = options.label ?? "local roots";
     const requestedPath = path.resolve(resolveLocalPathInput(options.filePath, "file path"));
     const rootDirs = options.roots.map((rootEntry) => resolveLocalRootInput(rootEntry, label));
@@ -147,8 +149,8 @@ export async function readLocalFileFromRoots(options) {
         };
         // Leave maxBytes absent when the caller omits it so Root's own default
         // cap remains in force instead of being overwritten by undefined.
-        if (options.maxBytes !== undefined) {
-            readOptions.maxBytes = options.maxBytes;
+        if (maxBytes !== undefined) {
+            readOptions.maxBytes = maxBytes;
         }
         // A trusted root symlink has two valid spellings. Preserve the caller's
         // lexical spelling when possible so Root.read() still enforces its

package/dist/native-binding.d.ts

@@ -1,3 +1,4 @@
+import type { TarMeterLimits } from "./archive-limits.js";
 export interface NativeFileHash {
     bytes: number;
     digest: string;
@@ -31,6 +32,11 @@ export interface NativeOpenBeneathResult {
     fd: number;
     containment: "kernel-atomic" | "best-effort";
 }
+export interface NativeOwnedTreeRemovalResult {
+    outcome?: "removed" | "preserved";
+    errorCode?: string;
+    errorMessage?: string;
+}
 export interface NativeWindowsAccessControlEntry {
     sid: string;
     mask: number;
@@ -62,17 +68,23 @@ export interface NativeWindowsSecurityFacts {
     aces: NativeWindowsAccessControlEntry[];
 }
 export interface NativeBinding {
+    createStagedFile?(parentFd: number, basename: string): number;
+    stagedFileMatches?(parentFd: number, basename: string, fileFd: number): boolean;
+    removeStagedFile?(parentFd: number, basename: string, fileFd: number): "removed" | "name-absent" | "preserved";
     cloneFileExclusive(sourceFd: number, targetRootFd: number, targetRelPath: string): number;
     copyFileRangeExclusive(sourceFd: number, targetRootFd: number, targetRelPath: string): Promise<NativeCopyResult>;
     createPrivateDirectory(path: string): void;
-    extractArchiveNative(path: string, kind: string, rootFd: number, plan: NativeArchivePlanEntry[], maxMetaEntryBytes: number, signal: AbortSignal): Promise<void>;
+    extractArchiveNative(path: string, kind: string, rootFd: number, plan: NativeArchivePlanEntry[], limits: TarMeterLimits, signal: AbortSignal): Promise<void>;
     fstatIdentity(fd: number): NativeFileIdentity;
-    inspectArchiveNative(path: string, kind: string, maxEntries: number, maxMetaEntryBytes: number, maxManifestBytes: number, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
+    inspectArchiveNative(path: string, kind: string, limits: TarMeterLimits, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
     linkBeneath(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
     mkdirBeneath(rootFd: number, relPath: string, mode: number): void;
     openBeneath(rootFd: number, relPath: string, flags: number): NativeOpenBeneathResult;
-    readArchiveEntryNative(path: string, kind: string, requested: string, maxBytes: number, maxEntries: number, maxMetaEntryBytes: number, signal: AbortSignal): Promise<Buffer>;
+    readArchiveEntryNative(path: string, kind: string, requested: string, maxBytes: number, limits: TarMeterLimits, signal: AbortSignal): Promise<Buffer>;
     readOwnerAndDacl(path: string): NativeWindowsSecurityFacts;
+    ownedTreeRemovalAvailable?(parentFd: number): boolean;
+    removeOwnedTree?(parentFd: number, basename: string, directoryFd: number): Promise<NativeOwnedTreeRemovalResult>;
+    removeOwnedTreeSync?(parentFd: number, basename: string, directoryFd: number): NativeOwnedTreeRemovalResult;
     renameNoReplace(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
     renameReplace(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
     sha256File(fd: number): Promise<NativeFileHash>;

package/dist/native-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-binding.d.ts","sourceRoot":"","sources":["../src/native-binding.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;CAAG;AAErE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,eAAe,GAAG,aAAa,CAAC;CAC9C;AAED,MAAM,WAAW,+BAA+B;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAC;QACZ,aAAa,EAAE,OAAO,CAAC;QACvB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,kBAAkB,EAAE,OAAO,CAAC;QAC5B,WAAW,EAAE,OAAO,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;QACnB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,+BAA+B,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1F,sBAAsB,CACpB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC7B,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,sBAAsB,EAAE,EAC9B,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAC9C,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,EACzB,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACjC,WAAW,CACT,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC;IACR,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAClE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,uBAAuB,CAAC;IACrF,sBAAsB,CACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,0BAA0B,CAAC;IAC3D,eAAe,CACb,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC;IACR,aAAa,CACX,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC;IACR,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACjD"}
+{"version":3,"file":"native-binding.d.ts","sourceRoot":"","sources":["../src/native-binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;CAAG;AAErE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,eAAe,GAAG,aAAa,CAAC;CAC9C;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,+BAA+B;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAC;QACZ,aAAa,EAAE,OAAO,CAAC;QACvB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,kBAAkB,EAAE,OAAO,CAAC;QAC5B,WAAW,EAAE,OAAO,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;QACnB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,+BAA+B,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAE5B,gBAAgB,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9D,iBAAiB,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAChF,gBAAgB,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;IAC/G,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1F,sBAAsB,CACpB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC7B,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,sBAAsB,EAAE,EAC9B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAC9C,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACjC,WAAW,CACT,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC;IACR,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAClE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,uBAAuB,CAAC;IACrF,sBAAsB,CACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,0BAA0B,CAAC;IAC3D,yBAAyB,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD,eAAe,CAAC,CACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACzC,mBAAmB,CAAC,CAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,4BAA4B,CAAC;IAChC,eAAe,CACb,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC;IACR,aAAa,CACX,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC;IACR,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACjD"}

package/dist/native-operations.d.ts

@@ -1,6 +1,7 @@
 import { type Stats } from "node:fs";
 import type { ContainmentGuarantee } from "./containment.js";
 import { type NativeBinding } from "./native.js";
+import type { PinnedWriteInput } from "./pinned-write.js";
 export type NativeFileHandle = {
     readonly fd: number;
     readonly containment: ContainmentGuarantee;
@@ -8,6 +9,9 @@ export type NativeFileHandle = {
     stat(): Promise<Stats>;
     writeFile(data: string | Buffer, encoding?: BufferEncoding): Promise<void>;
 };
+export declare function nativeOpenFlags(flags: number): number;
+export declare function writeNativeFd(fd: number, data: Buffer): void;
+export declare function writeNativeInput(fd: number, input: PinnedWriteInput, maxBytes?: number): Promise<void>;
 export declare function removeNativeCreatedFileIfStillPinned(params: {
     binding: NativeBinding;
     parentPath: string;
@@ -17,5 +21,4 @@ export declare function removeNativeCreatedFileIfStillPinned(params: {
 }): void;
 export declare function createNativeExclusiveFile(targetPath: string, mode: number): Promise<NativeFileHandle | undefined>;
 export declare function syncNativeFileBestEffort(fd: number): void;
-export declare function writeNativeFd(fd: number, data: Buffer): void;
 //# sourceMappingURL=native-operations.d.ts.map

package/dist/native-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-operations.d.ts","sourceRoot":"","sources":["../src/native-operations.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E,CAAC;AA0CF,wBAAgB,oCAAoC,CAAC,MAAM,EAAE;IAC3D,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB,GAAG,IAAI,CAsBP;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAyDvC;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAQzD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D"}
+{"version":3,"file":"native-operations.d.ts","sourceRoot":"","sources":["../src/native-operations.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOrD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAS5D;AAED,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,gBAAgB,EACvB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAsBD,wBAAgB,oCAAoC,CAAC,MAAM,EAAE;IAC3D,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB,GAAG,IAAI,CAsBP;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAyDvC;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAQzD"}

package/dist/native-operations.js

@@ -1,15 +1,16 @@
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { getNativeBinding } from "./native.js";
-function nativeOpenFlags(flags) {
+export function nativeOpenFlags(flags) {
     const closeOnExec = fsSync.constants.O_CLOEXEC;
     return (flags |
         (closeOnExec ?? 0) |
         (typeof fsSync.constants.O_NOFOLLOW === "number" ? fsSync.constants.O_NOFOLLOW : 0));
 }
-function writeAll(fd, data) {
+export function writeNativeFd(fd, data) {
     let offset = 0;
     while (offset < data.byteLength) {
         const written = fsSync.writeSync(fd, data, offset, data.byteLength - offset);
@@ -19,6 +20,24 @@ function writeAll(fd, data) {
         offset += written;
     }
 }
+export async function writeNativeInput(fd, input, maxBytes) {
+    let bytes = 0;
+    const write = (data) => {
+        bytes += data.byteLength;
+        if (maxBytes !== undefined && bytes > maxBytes) {
+            throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
+        }
+        writeNativeFd(fd, data);
+    };
+    if (input.kind === "buffer") {
+        write(typeof input.data === "string" ? Buffer.from(input.data, input.encoding ?? "utf8") : input.data);
+    }
+    else {
+        for await (const chunk of input.stream) {
+            write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+    }
+}
 function wrapNativeFd(fd, containment) {
     let open = true;
     return {
@@ -34,7 +53,7 @@ function wrapNativeFd(fd, containment) {
             return fsSync.fstatSync(fd);
         },
         async writeFile(data, encoding) {
-            writeAll(fd, Buffer.isBuffer(data) ? data : Buffer.from(data, encoding ?? "utf8"));
+            writeNativeFd(fd, Buffer.isBuffer(data) ? data : Buffer.from(data, encoding ?? "utf8"));
         },
     };
 }
@@ -123,6 +142,3 @@ export function syncNativeFileBestEffort(fd) {
         }
     }
 }
-export function writeNativeFd(fd, data) {
-    writeAll(fd, data);
-}

package/dist/native-pinned-write-windows.d.ts

@@ -0,0 +1,8 @@
+import type { FileHandle } from "node:fs/promises";
+import type { AsyncDirectoryGuard } from "./directory-guard.js";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { NativeBinding } from "./native.js";
+import type { PinnedWriteParams } from "./pinned-write.js";
+export declare function sameNativeIdentity(left: Pick<FileIdentityStat, "dev" | "ino">, right: Pick<FileIdentityStat, "dev" | "ino">): boolean;
+export declare function runPinnedWriteWindows(binding: NativeBinding, params: PinnedWriteParams, root: FileHandle, parentFd: number, parentGuard: AsyncDirectoryGuard): Promise<FileIdentityStat>;
+//# sourceMappingURL=native-pinned-write-windows.d.ts.map

package/dist/native-pinned-write-windows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-pinned-write-windows.d.ts","sourceRoot":"","sources":["../src/native-pinned-write-windows.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAO3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,KAAK,CAAC,EAC3C,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,KAAK,CAAC,GAC3C,OAAO,CAET;AAWD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,mBAAmB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAgF3B"}

package/dist/native-pinned-write-windows.js

@@ -0,0 +1,92 @@
+import { randomUUID } from "node:crypto";
+import fsSync, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { nativeOpenFlags, removeNativeCreatedFileIfStillPinned, syncNativeFileBestEffort, writeNativeInput, } from "./native-operations.js";
+export function sameNativeIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function closeWriteFd(fd) {
+    if (fd === undefined)
+        return;
+    try {
+        fsSync.closeSync(fd);
+    }
+    catch (error) {
+        return error;
+    }
+}
+export async function runPinnedWriteWindows(binding, params, root, parentFd, parentGuard) {
+    const parentPath = parentGuard.realPath;
+    let tempFd;
+    let targetFd;
+    let tempIdentity;
+    let tempName = "";
+    let renamed = false;
+    let completed = false;
+    try {
+        tempName = `.${params.basename}.${randomUUID()}.native.tmp`;
+        tempFd = binding.openBeneath(parentFd, tempName, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL)).fd;
+        tempIdentity = fsSync.fstatSync(tempFd);
+        const verificationIdentity = fsSync.fstatSync(tempFd, { bigint: true });
+        // Creation is requested at 0600 in the binding, but a restrictive umask
+        // can remove owner access. Keep the unpublished inode private and
+        // reopenable until the published name has been identity-fenced.
+        fsSync.fchmodSync(tempFd, 0o600);
+        await writeNativeInput(tempFd, params.input, params.maxBytes);
+        syncNativeFileBestEffort(tempFd);
+        if (params.overwrite === false) {
+            binding.renameNoReplace(parentFd, tempName, parentFd, params.basename);
+        }
+        else {
+            binding.renameReplace(parentFd, tempName, parentFd, params.basename);
+        }
+        renamed = true;
+        targetFd = binding.openBeneath(parentFd, params.basename, nativeOpenFlags(fsSync.constants.O_RDONLY)).fd;
+        const targetIdentity = binding.fstatIdentity(targetFd);
+        if (!targetIdentity.isFile || !sameNativeIdentity(tempIdentity, targetIdentity)) {
+            throw new FsSafeError("path-mismatch", "native write target changed after rename");
+        }
+        // Native exclusive creation starts at 0600. Apply the requested mode only
+        // after reopening and fencing the published name, both so mode 000 stays
+        // verifiable and so broader modes are never exposed before that fence.
+        try {
+            fsSync.fchmodSync(targetFd, params.mode);
+            syncNativeFileBestEffort(targetFd);
+        }
+        catch (error) {
+            closeWriteFd(targetFd);
+            targetFd = undefined;
+            removeNativeCreatedFileIfStillPinned({
+                binding,
+                parentPath,
+                parentFd,
+                basename: params.basename,
+                created: tempIdentity,
+            });
+            throw error;
+        }
+        syncNativeFileBestEffort(parentFd);
+        // Verification follows publication and final chmod, outside rollback handling.
+        await params.verifyPublished?.(targetFd, verificationIdentity, parentGuard);
+        completed = true;
+        return { dev: targetIdentity.dev, ino: targetIdentity.ino };
+    }
+    finally {
+        const targetCloseError = closeWriteFd(targetFd);
+        const tempCloseError = closeWriteFd(tempFd);
+        if (!renamed) {
+            removeNativeCreatedFileIfStillPinned({
+                binding,
+                parentPath,
+                parentFd,
+                basename: tempName,
+                created: tempIdentity,
+            });
+        }
+        const parentCloseError = closeWriteFd(parentFd);
+        await root.close().catch(() => undefined);
+        const closeError = targetCloseError ?? tempCloseError ?? parentCloseError;
+        if (completed && closeError !== undefined)
+            throw closeError;
+    }
+}

package/dist/native-pinned-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-pinned-write.d.ts","sourceRoot":"","sources":["../src/native-pinned-write.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAM3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAoB,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAiD7E,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAsH3B"}
+{"version":3,"file":"native-pinned-write.d.ts","sourceRoot":"","sources":["../src/native-pinned-write.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmFvH"}