@openclaw/fs-safe 0.15.0 → 0.17.0

package/dist/windows-security-command.js

@@ -0,0 +1,363 @@
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { FsSafeError } from "./errors.js";
+import { DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, PermissionCommandError } from "./permission-exec.js";
+import { resolveWindowsSystemCommand } from "./windows-command.js";
+import { parseWindowsSecurityCommandFacts } from "./windows-security-facts.js";
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+const TERMINATION_GRACE_MS = 1_000;
+const FULL_IDENTITY = /^[0-9a-f]{16}:[0-9a-f]{32}$/;
+function isFullIdentity(identity) {
+    return typeof identity === "string" && identity.length === 49 && FULL_IDENTITY.test(identity);
+}
+function assertIdentity(identity) {
+    if (!isFullIdentity(identity)) {
+        throw new TypeError("Windows security operation requires a complete file identity");
+    }
+}
+function command(operation, params) {
+    const targetPath = params.targetPath ?? "";
+    // Preserve native EINVAL before child-process environment validation runs.
+    if (targetPath.includes("\0")) {
+        throw Object.assign(new Error("Windows path contains a NUL byte"), { code: "EINVAL" });
+    }
+    if (params.fd !== undefined || operation === "descriptor" || operation === "protect-file" || operation === "verify-file") {
+        if (typeof params.fd !== "number" || !Number.isInteger(params.fd) || params.fd < 0 || params.fd > 0x7fff_ffff) {
+            unverified("Windows security inspection requires a valid descriptor");
+        }
+    }
+    if (params.expectedParentIdentity !== undefined)
+        assertIdentity(params.expectedParentIdentity);
+    if (params.expectedFileIdentity !== undefined)
+        assertIdentity(params.expectedFileIdentity);
+    if (params.expectedLinks !== undefined &&
+        (!Number.isInteger(params.expectedLinks) || params.expectedLinks < 1 || params.expectedLinks > 0xffff_ffff)) {
+        throw new TypeError("Windows security operation requires a positive uint32 link count");
+    }
+    const script = fileURLToPath(new URL("./windows-security-bridge.ps1", import.meta.url));
+    return {
+        file: resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`),
+        args: ["-NoLogo", "-NoProfile", "-NonInteractive", "-File", script, "-Operation", operation],
+        // Preserve Windows UTF-16 spelling and leave long paths out of the bounded
+        // command line. This overrides any inherited value only in this child.
+        env: {
+            ...process.env,
+            FS_SAFE_WINDOWS_SECURITY_PATH: targetPath,
+            FS_SAFE_WINDOWS_SECURITY_REQUIRE_PRIVATE: params.requirePrivate ? "1" : "0",
+            FS_SAFE_WINDOWS_SECURITY_PARENT_IDENTITY: params.expectedParentIdentity ?? "",
+            FS_SAFE_WINDOWS_SECURITY_FILE_IDENTITY: params.expectedFileIdentity ?? "",
+            FS_SAFE_WINDOWS_SECURITY_EXPECTED_LINKS: String(params.expectedLinks ?? 1),
+        },
+    };
+}
+function unverified(message, cause) {
+    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseReply(stdout, operation) {
+    try {
+        return parseReplyValue(stdout, operation);
+    }
+    catch (error) {
+        if (operation === "create" && error instanceof Error && error.code !== "EEXIST") {
+            Object.assign(error, { creationOutcome: "unconfirmed" });
+        }
+        throw error;
+    }
+}
+function parseReplyValue(stdout, operation) {
+    let response;
+    try {
+        response = JSON.parse(stdout.trim());
+    }
+    catch (cause) {
+        unverified("Windows security command returned invalid data", cause);
+    }
+    if (!record(response) || typeof response.ok !== "boolean") {
+        unverified("Windows security command returned an incomplete response");
+    }
+    if (!response.ok) {
+        const codes = new Set(["EACCES", "EPERM", "EEXIST", "ENOENT", "ENOTSUP", "EIO", "EBADF", "ELOOP", "ENOTDIR", "EINVAL", "ENOSPC", "EBUSY"]);
+        if (typeof response.code !== "string" || !codes.has(response.code) || typeof response.message !== "string") {
+            unverified("Windows security command returned an invalid failure");
+        }
+        throw Object.assign(new Error(response.message), { code: response.code });
+    }
+    if (operation === "create" && (!record(response.result) || response.result.created !== true || !isFullIdentity(response.result.identity))) {
+        unverified("Windows security command did not verify private-directory creation");
+    }
+    return response.result;
+}
+function executeSync(operation, params) {
+    const { file, args, env } = command(operation, params);
+    const startedAt = performance.now();
+    const result = spawnSync(file, args, {
+        encoding: "utf8", windowsHide: true, env, stdio: [params.fd ?? "ignore", "pipe", "pipe"],
+        timeout: DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, killSignal: "SIGKILL", maxBuffer: MAX_OUTPUT_BYTES,
+    });
+    if (result.error || result.status !== 0) {
+        const error = new PermissionCommandError(file, performance.now() - startedAt, {
+            cause: result.error, code: result.status,
+            signal: result.error?.code === "ETIMEDOUT" ? "SIGKILL" : result.signal,
+            stderr: result.stderr,
+            killed: result.error?.code === "ETIMEDOUT",
+            ...(operation === "create" ? { creationOutcome: "unconfirmed" } : {}),
+        });
+        if (operation === "create")
+            Object.assign(error, { creationOutcome: "unconfirmed" });
+        throw error;
+    }
+    return parseReply(result.stdout, operation);
+}
+class WindowsSecurityCommandError extends PermissionCommandError {
+    timedOut;
+    creationOutcome;
+    processExitConfirmed;
+    constructor(file, durationMs, receipt, timedOut) {
+        super(file, durationMs, receipt);
+        this.timedOut = timedOut;
+        this.creationOutcome = receipt.creationOutcome;
+        this.processExitConfirmed = receipt.processExitConfirmed;
+        if (timedOut)
+            this.message = `Windows permission inspection timed out after ${DEFAULT_PERMISSION_EXEC_TIMEOUT_MS}ms`;
+        if (!receipt.processExitConfirmed)
+            this.message += "; process exit was not confirmed";
+        else if (!receipt.outputClosed)
+            this.message += "; command output did not close";
+        if (receipt.creationOutcome)
+            this.message += "; private-directory creation outcome is unconfirmed";
+    }
+}
+/** Cleanup must preserve stages still reachable by an unsettled command. */
+export function hasUnsettledWindowsSecurityCommand(error) {
+    const pending = [error];
+    const seen = new Set();
+    for (let inspected = 0; pending.length && inspected < 32; inspected++) {
+        const current = pending.pop();
+        if (current === null || typeof current !== "object" || seen.has(current))
+            continue;
+        seen.add(current);
+        try {
+            if (current instanceof WindowsSecurityCommandError && !current.processExitConfirmed)
+                return true;
+            const cause = Object.getOwnPropertyDescriptor(current, "cause");
+            if (cause && "value" in cause)
+                pending.push(cause.value);
+            if (current instanceof AggregateError) {
+                const errors = Object.getOwnPropertyDescriptor(current, "errors");
+                if (errors && "value" in errors && Array.isArray(errors.value))
+                    pending.push(...errors.value.slice(0, 32));
+            }
+        }
+        catch {
+            // Unknown error wrappers cannot prove that command-owned handles settled.
+            return true;
+        }
+    }
+    return pending.length > 0;
+}
+function ignoreLateError() { }
+async function execute(operation, params) {
+    const { file, args, env } = command(operation, params);
+    const startedAt = performance.now();
+    return await new Promise((resolve, reject) => {
+        const child = spawn(file, args, { windowsHide: true, env, stdio: [params.fd ?? "ignore", "pipe", "pipe"] });
+        const output = [];
+        const errors = [];
+        let bytes = 0;
+        let failure;
+        let failed = false;
+        let timedOut = false;
+        let stopping = false;
+        let settled = false;
+        let processExitConfirmed = false;
+        let exitCode = null;
+        let exitSignal = null;
+        let terminationSignalSent;
+        let terminationError;
+        let grace;
+        let missingPipes;
+        const deadlineError = () => new Error("Windows security command exceeded its inspection deadline");
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            fail(deadlineError());
+        }, DEFAULT_PERMISSION_EXEC_TIMEOUT_MS);
+        const finish = (outputClosed) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            clearTimeout(grace);
+            clearImmediate(missingPipes);
+            child.removeListener("exit", onExit);
+            child.removeListener("close", onClose);
+            child.removeListener("error", onChildError);
+            child.on("error", ignoreLateError);
+            const cleanupErrors = [];
+            for (const [stream, collect] of [[child.stdout, collectOutput], [child.stderr, collectErrors]]) {
+                if (!stream)
+                    continue;
+                stream.removeListener("data", collect);
+                stream.removeListener("error", fail);
+                stream.on("error", ignoreLateError);
+                if (!outputClosed) {
+                    try {
+                        stream.destroy();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+            }
+            if (!outputClosed && !processExitConfirmed) {
+                try {
+                    child.unref();
+                }
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+            }
+            if (failed || exitCode !== 0 || !outputClosed) {
+                reject(new WindowsSecurityCommandError(file, performance.now() - startedAt, {
+                    cause: failure, pid: child.pid ?? null, code: exitCode, signal: exitSignal, stderr: Buffer.concat(errors),
+                    processExitConfirmed, outputClosed, terminationSignalSent, terminationError, cleanupErrors,
+                    ...(operation === "create" ? { creationOutcome: "unconfirmed" } : {}),
+                }, timedOut));
+            }
+            else {
+                try {
+                    resolve(parseReply(Buffer.concat(output).toString("utf8"), operation));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }
+            output.length = 0;
+            errors.length = 0;
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            if (!failed) {
+                failed = true;
+                failure = error;
+            }
+            if (stopping)
+                return;
+            stopping = true;
+            clearTimeout(timeout);
+            // kill() can synchronously emit error, throw, or return false. None proves exit.
+            grace = setTimeout(() => finish(false), TERMINATION_GRACE_MS);
+            if (!processExitConfirmed) {
+                try {
+                    terminationSignalSent = child.kill("SIGKILL");
+                }
+                catch (error) {
+                    terminationError ??= error;
+                }
+            }
+        };
+        const collect = (chunks) => (chunk) => {
+            if (failed || settled)
+                return;
+            bytes += chunk.length;
+            if (bytes <= MAX_OUTPUT_BYTES)
+                chunks.push(chunk);
+            else
+                fail(new Error("Windows security command exceeded its output budget"));
+        };
+        const collectOutput = collect(output);
+        const collectErrors = collect(errors);
+        const onChildError = (error) => {
+            if (settled)
+                return;
+            if (stopping)
+                terminationError ??= error;
+            else
+                fail(error);
+        };
+        const onExit = (code, signal) => {
+            processExitConfirmed = true;
+            exitCode = code;
+            exitSignal = signal;
+        };
+        const onClose = (code, signal) => {
+            onExit(code, signal);
+            if (!failed && performance.now() - startedAt >= DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+                timedOut = true;
+                failed = true;
+                failure = deadlineError();
+            }
+            finish(true);
+        };
+        child.on("error", onChildError);
+        child.once("exit", onExit);
+        // Success still joins exit and both pipes. Failure releases only owned endpoints
+        // after grace; the child inherited its own HANDLE, independent of the caller fd.
+        child.once("close", onClose);
+        child.stdout?.on("error", fail);
+        child.stderr?.on("error", fail);
+        child.stdout?.on("data", collectOutput);
+        child.stderr?.on("data", collectErrors);
+        if (!child.stdout || !child.stderr) {
+            // Node reports spawn errors on nextTick, which can follow the current microtask.
+            missingPipes = setImmediate(() => { if (!failed && !settled)
+                fail(new Error("Windows security command output pipes are unavailable")); });
+        }
+    });
+}
+export function readWindowsSecurityFactsCommand(targetPath) {
+    return parseWindowsSecurityCommandFacts(executeSync("path", { targetPath }));
+}
+export async function inspectWindowsDescriptorCommand(fd) {
+    const response = await execute("descriptor", { fd });
+    if (!record(response) || typeof response.identity !== "string") {
+        unverified("Windows security command returned incomplete handle facts");
+    }
+    return { identity: response.identity, security: parseWindowsSecurityCommandFacts(response.security) };
+}
+export async function createPrivateWindowsDirectoryCommand(targetPath, expectedParentIdentity) {
+    return fullIdentityReceipt(await execute("create", { targetPath, expectedParentIdentity }));
+}
+export function createPrivateWindowsDirectoryCommandSync(targetPath, expectedParentIdentity) {
+    return fullIdentityReceipt(executeSync("create", { targetPath, expectedParentIdentity }));
+}
+function fullIdentityReceipt(response, expected) {
+    if (!record(response) || !isFullIdentity(response.identity)) {
+        unverified("Windows security command returned an incomplete file identity");
+    }
+    if (expected !== undefined && response.identity !== expected) {
+        throw new FsSafeError("path-mismatch", "Windows security command observed a different file");
+    }
+    return { identity: response.identity };
+}
+export function inspectWindowsDirectoryCommandSync(targetPath, requirePrivate) {
+    return fullIdentityReceipt(executeSync("directory", { targetPath, requirePrivate }));
+}
+export async function inspectWindowsDirectoryCommand(targetPath, requirePrivate) {
+    return fullIdentityReceipt(await execute("directory", { targetPath, requirePrivate }));
+}
+export function protectPrivateWindowsFileCommandSync(fd, targetPath, expectedParentIdentity) {
+    assertIdentity(expectedParentIdentity);
+    return fullIdentityReceipt(executeSync("protect-file", { fd, targetPath, expectedParentIdentity }));
+}
+export async function protectPrivateWindowsFileCommand(fd, targetPath, expectedParentIdentity) {
+    assertIdentity(expectedParentIdentity);
+    return fullIdentityReceipt(await execute("protect-file", { fd, targetPath, expectedParentIdentity }));
+}
+export function verifyPrivateWindowsFileCommandSync(fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks = 1) {
+    assertIdentity(expectedFileIdentity);
+    assertIdentity(expectedParentIdentity);
+    fullIdentityReceipt(executeSync("verify-file", {
+        fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks,
+    }), expectedFileIdentity);
+}
+export async function verifyPrivateWindowsFileCommand(fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks = 1) {
+    assertIdentity(expectedFileIdentity);
+    assertIdentity(expectedParentIdentity);
+    fullIdentityReceipt(await execute("verify-file", {
+        fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks,
+    }), expectedFileIdentity);
+}

package/dist/windows-security-facts.d.ts

@@ -0,0 +1,6 @@
+import type { NativeWindowsSecurityFacts } from "./native-binding.js";
+/** Raw reporting retains unknown flag bits; secure admission validates them below. */
+export declare function parseWindowsSecurityCommandFacts(value: unknown): NativeWindowsSecurityFacts;
+/** Native and command observations share the same fail-closed admission policy. */
+export declare function validateSecureWindowsSecurityFacts(value: unknown): NativeWindowsSecurityFacts;
+//# sourceMappingURL=windows-security-facts.d.ts.map

package/dist/windows-security-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-security-facts.d.ts","sourceRoot":"","sources":["../src/windows-security-facts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmC,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAmFvG,sFAAsF;AACtF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAU3F;AAED,mFAAmF;AACnF,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAoB7F"}

package/dist/windows-security-facts.js

@@ -0,0 +1,108 @@
+import { FsSafeError } from "./errors.js";
+const SID_RE = /^s-\d+-\d+(?:-\d+)+$/;
+const SYSTEM_SID = "s-1-5-18";
+const ADMINISTRATORS_SID = "s-1-5-32-544";
+const WORLD_SIDS = new Set([
+    "s-1-1-0", "s-1-5-11", "s-1-5-32-545", "s-1-5-7",
+    "s-1-5-32-546", "s-1-5-4", "s-1-5-2",
+]);
+function unverified(message) {
+    throw new FsSafeError("permission-unverified", message);
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function uint32(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 0xffff_ffff;
+}
+function validateAce(value, allowUnknownFlags) {
+    if (!record(value) || typeof value.sid !== "string" || !SID_RE.test(value.sid) ||
+        !uint32(value.mask) || (value.aceType !== "allow" && value.aceType !== "deny") ||
+        !record(value.flags))
+        return false;
+    const { raw } = value.flags;
+    if (!uint32(raw) || (raw & ~(allowUnknownFlags ? 0xff : 0xdf)) !== 0)
+        return false;
+    const fields = [
+        ["objectInherit", 0x01], ["containerInherit", 0x02],
+        ["noPropagateInherit", 0x04], ["inheritOnly", 0x08], ["inherited", 0x10],
+        ["successfulAccess", 0x40], ["failedAccess", 0x80],
+    ];
+    const flags = value.flags;
+    return fields.every(([field, bit]) => typeof flags[field] === "boolean" && flags[field] === ((raw & bit) !== 0));
+}
+function validateDescriptor(value, allowUnknownFlags) {
+    if (!record(value) || typeof value.ownerSid !== "string" || !SID_RE.test(value.ownerSid) ||
+        typeof value.currentUserSid !== "string" || !SID_RE.test(value.currentUserSid) ||
+        typeof value.daclPresent !== "boolean" || typeof value.isLocal !== "boolean" ||
+        typeof value.aceListComplete !== "boolean" || !Array.isArray(value.unsupportedAceTypes) ||
+        !value.unsupportedAceTypes.every(uint32) || !Array.isArray(value.aces) ||
+        !value.aces.every(ace => validateAce(ace, allowUnknownFlags))) {
+        unverified("Windows descriptor ACL facts were malformed");
+    }
+    if ((!value.daclPresent && value.aces.length !== 0) ||
+        (value.aceListComplete && value.unsupportedAceTypes.length !== 0)) {
+        unverified("Windows descriptor DACL facts were inconsistent");
+    }
+    return value;
+}
+function summarize(facts) {
+    const ownerClass = facts.ownerSid === facts.currentUserSid ? "current-user"
+        : facts.ownerSid === SYSTEM_SID ? "system"
+            : facts.ownerSid === ADMINISTRATORS_SID ? "administrators" : "foreign";
+    let worldReadable = !facts.daclPresent;
+    let worldWritable = !facts.daclPresent;
+    let groupReadable = false;
+    let groupWritable = false;
+    const trusted = new Set([facts.currentUserSid, SYSTEM_SID, ADMINISTRATORS_SID]);
+    for (const ace of facts.aces) {
+        if (ace.aceType !== "allow" || ace.flags.inheritOnly || trusted.has(ace.sid))
+            continue;
+        // Generic and file-specific read/write, delete, and security-control rights.
+        const canRead = (ace.mask & 0x9000_0089) !== 0;
+        const canWrite = (ace.mask & 0x500d_0156) !== 0;
+        if (WORLD_SIDS.has(ace.sid)) {
+            worldReadable ||= canRead;
+            worldWritable ||= canWrite;
+        }
+        else {
+            groupReadable ||= canRead;
+            groupWritable ||= canWrite;
+        }
+    }
+    return { ownerClass, worldReadable, worldWritable, groupReadable, groupWritable };
+}
+/** Raw reporting retains unknown flag bits; secure admission validates them below. */
+export function parseWindowsSecurityCommandFacts(value) {
+    const facts = validateDescriptor(value, true);
+    if (!record(value) || typeof value.daclProtected !== "boolean") {
+        unverified("Windows security command returned malformed descriptor facts");
+    }
+    return {
+        ...facts,
+        ...summarize(facts),
+        fallbackRequired: !facts.isLocal || !facts.aceListComplete,
+    };
+}
+/** Native and command observations share the same fail-closed admission policy. */
+export function validateSecureWindowsSecurityFacts(value) {
+    const descriptor = validateDescriptor(value, false);
+    const facts = value;
+    const summary = summarize(descriptor);
+    const booleans = ["worldWritable", "groupWritable", "worldReadable", "groupReadable", "fallbackRequired"];
+    if (!booleans.every(field => typeof facts[field] === "boolean") ||
+        typeof facts.ownerClass !== "string") {
+        unverified("Windows descriptor ACL facts were malformed");
+    }
+    if (facts.ownerClass !== summary.ownerClass) {
+        unverified("Windows descriptor owner facts were inconsistent");
+    }
+    if (facts.fallbackRequired || !facts.isLocal || !facts.aceListComplete || facts.unsupportedAceTypes.length !== 0) {
+        unverified("Windows descriptor ACL facts were incomplete or unsupported");
+    }
+    if (facts.worldReadable !== summary.worldReadable || facts.worldWritable !== summary.worldWritable ||
+        facts.groupReadable !== summary.groupReadable || facts.groupWritable !== summary.groupWritable) {
+        unverified("Windows descriptor ACL summary was inconsistent");
+    }
+    return facts;
+}

package/dist/write-file-handle.d.ts

@@ -1,4 +1,11 @@
 import type { FileHandle } from "node:fs/promises";
+export type WriteFileWindowOptions = {
+    signal?: AbortSignal;
+    /** Synchronous authority check immediately before every write, including short-write retries. */
+    assertBeforeMutation?: () => void;
+};
+/** Write borrowed bytes completely; null advances the cursor, an explicit position preserves it. */
+export declare function writeFileWindowFully(handle: FileHandle, bytes: Uint8Array, position: number | null, options?: WriteFileWindowOptions): Promise<void>;
 export declare function writeAllToFile(target: FileHandle | number, data: string | Uint8Array, options?: {
     encoding?: BufferEncoding;
     position?: number;

package/dist/write-file-handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-file-handle.d.ts","sourceRoot":"","sources":["../src/write-file-handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAChG,OAAO,CAAC,IAAI,CAAC,CAoBf"}
+{"version":3,"file":"write-file-handle.d.ts","sourceRoot":"","sources":["../src/write-file-handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAOnD,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iGAAiG;IACjG,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC;AAEF,oGAAoG;AACpG,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAChG,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/write-file-handle.js

@@ -1,6 +1,29 @@
 import fs from "node:fs";
+import { snapshotByteView } from "./byte-view.js";
 import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 const WRITE_CHUNK_BYTES = 512 * 1024;
+/** Write borrowed bytes completely; null advances the cursor, an explicit position preserves it. */
+export async function writeFileWindowFully(handle, bytes, position, options = {}) {
+    const payload = snapshotByteView(bytes);
+    if (position !== null && (!Number.isSafeInteger(position) || position < 0 ||
+        !Number.isSafeInteger(position + payload.byteLength))) {
+        throw new RangeError("write position and window end must be non-negative safe integers");
+    }
+    const signal = options.signal;
+    const assertion = options.assertBeforeMutation;
+    signal?.throwIfAborted();
+    await writeAllToFile(handle, payload, {
+        position: position === null ? undefined : position,
+        assertBeforeMutation: () => {
+            signal?.throwIfAborted();
+            assertSynchronousCallbackResult(assertion === undefined ? undefined : Reflect.apply(assertion, options, []), "assertBeforeMutation");
+            signal?.throwIfAborted();
+        },
+    });
+    // A pending write must settle before cancellation releases the caller's buffer and handle.
+    signal?.throwIfAborted();
+}
 export async function writeAllToFile(target, data, options = {}) {
     const buffer = typeof data === "string" ? Buffer.from(data, options.encoding ?? "utf8") : data;
     let offset = 0;

package/dist/write-open-flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-open-flags.d.ts","sourceRoot":"","sources":["../src/write-open-flags.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAG7B,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAoB,GACjF,MAAM,CAIR;AAUD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}
+{"version":3,"file":"write-open-flags.d.ts","sourceRoot":"","sources":["../src/write-open-flags.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAG7B,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAoB,GACjF,MAAM,CAIR;AAUD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}

package/dist/write-open-flags.js

@@ -13,14 +13,7 @@ function isNonblockingWriteEnxio(error, flags) {
 // A no-reader FIFO rejects a nonblocking write-only open before fstat is possible.
 // Reclassify only a confirmed non-regular path; inconclusive races keep the errno.
 export async function isNonRegularWriteOpenError(error, filePath, flags) {
-    if (!isNonblockingWriteEnxio(error, flags))
-        return false;
-    try {
-        return !fsSync.lstatSync(filePath).isFile();
-    }
-    catch {
-        return false;
-    }
+    return isNonRegularWriteOpenErrorSync(error, filePath, flags);
 }
 export function isNonRegularWriteOpenErrorSync(error, filePath, flags) {
     if (!isNonblockingWriteEnxio(error, flags))

package/dist/write-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-queue.d.ts","sourceRoot":"","sources":["../src/write-queue.ts"],"names":[],"mappings":"AAEA,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAkB1F"}
+{"version":3,"file":"write-queue.d.ts","sourceRoot":"","sources":["../src/write-queue.ts"],"names":[],"mappings":"AAEA,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAe1F"}

package/dist/write-queue.js

@@ -1,10 +1,7 @@
 const writeQueues = new Map();
 export async function serializePathWrite(key, run) {
     const previous = writeQueues.get(key) ?? Promise.resolve();
-    const task = (async () => {
-        await previous.catch(() => undefined);
-        return await run();
-    })();
+    const task = previous.then(() => run());
     const done = task.then(() => undefined, () => undefined);
     writeQueues.set(key, done);
     try {