@openclaw/fs-safe 0.9.0 → 0.10.0

package/dist/native-staged-file.js

@@ -54,9 +54,13 @@ import { requireNativeBinding } from "./native.js";
 import { syncFileBestEffortSync } from "./file-sync.js";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
+import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { MutationAuthorityError } from "./mutation-authority.js";
 import { writeNativeInput } from "./native-operations.js";
+import { assertNativeCopyCompleted, createNativeCopyFile } from "./copy-file-input.js";
 import { assertStagedDirectoryCurrent, openStagedDirectory } from "./staged-directory.js";
+import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 export function assertNativeStaging(binding) {
     if ([
         binding.createStagedFile,
@@ -93,24 +97,27 @@ class NativeStagedFile {
     #portableNames;
     #publishedMode;
     #sync;
+    #assertBeforeMutation;
     #name = `.fs-safe-${randomUUID()}.tmp`;
     #state = { status: "open", publication: NOT_PUBLISHED };
     #receipt;
-    constructor(binding, parentFd, directory, portableNames, publishedMode, sync) {
+    #rejectFinalSymlink = false;
+    constructor(binding, parentFd, directory, portableNames, publishedMode, sync, assertBeforeMutation) {
         this.#binding = binding;
         this.#parentFd = parentFd;
         this.#directory = directory;
         this.#portableNames = portableNames;
         this.#publishedMode = publishedMode;
         this.#sync = sync;
+        this.#assertBeforeMutation = assertBeforeMutation;
     }
     // Takes ownership of parentFd, including all construction and preparation failures.
     static async create(binding, parentFd, directory, input, mode, maxBytes, 
     // Public staging uses portable names; existing POSIX writes accept literal names.
-    portableNames = true, sync = true) {
+    portableNames = true, sync = true, assertBeforeMutation) {
         let staged;
         try {
-            staged = new NativeStagedFile(binding, parentFd, directory, portableNames, mode, sync);
+            staged = new NativeStagedFile(binding, parentFd, directory, portableNames, mode, sync, assertBeforeMutation);
         }
         catch (error) {
             try {
@@ -129,8 +136,11 @@ class NativeStagedFile {
         try {
             // This owner never escapes. Only the internal verifier borrows its fd;
             // public descriptor methods remain await-free and cannot race disposal.
-            const staged = __addDisposableResource(env_1, await NativeStagedFile.create(binding, parentFd, directory, params.input, params.mode, params.maxBytes, false, params.sync), true);
-            const published = await staged.publish(params.basename, { overwrite: params.overwrite !== false });
+            const staged = __addDisposableResource(env_1, await NativeStagedFile.create(binding, parentFd, directory, params.input, params.mode, params.maxBytes, false, params.sync, params.assertBeforeMutation), true);
+            staged.#rejectFinalSymlink = params.rejectFinalSymlink === true;
+            if (params.input.kind === "file")
+                await params.input.verifySource();
+            const published = await staged.publish(params.basename, { overwrite: params.overwrite !== false }, params.onPublished);
             const identity = published.staged.identity;
             await params.verifyPublished?.(staged.#file(), identity, parentGuard);
             return { dev: identity.dev, ino: identity.ino };
@@ -190,10 +200,22 @@ class NativeStagedFile {
             // The exclusive open performs no fallible post-open checks. Store its fd
             // before every subsequent operation, including the first metadata read.
             const state = this.#open();
-            state.fileFd = this.#binding.createStagedFile(this.#parentFd, this.#name);
+            this.#assertBeforeMutation?.();
+            const copied = input.kind === "file"
+                ? await createNativeCopyFile(this.#binding, input, this.#parentFd, this.#name, maxBytes, false)
+                : undefined;
+            state.fileFd = copied?.fd;
+            if (state.fileFd === undefined) {
+                this.#assertBeforeMutation?.();
+                state.fileFd = this.#binding.createStagedFile(this.#parentFd, this.#name);
+            }
             const fd = state.fileFd;
+            if (input.kind === "file")
+                assertNativeCopyCompleted(input, copied);
+            this.#assertBeforeMutation?.();
             fs.fchmodSync(fd, 0o600);
-            await writeNativeInput(fd, input, maxBytes);
+            if (!copied)
+                await writeNativeInput(fd, input, maxBytes, this.#assertBeforeMutation);
             if (this.#sync)
                 syncFileBestEffortSync(fd);
             const stat = fs.fstatSync(fd, { bigint: true });
@@ -230,7 +252,7 @@ class NativeStagedFile {
     async assertCurrent() {
         this.#assertCurrent();
     }
-    async publish(basename, options) {
+    async publish(basename, options, onPublished) {
         const overwrite = options?.overwrite;
         try {
             const state = this.#open();
@@ -239,6 +261,8 @@ class NativeStagedFile {
                 throw new FsSafeError("invalid-path", "publication needs a distinct basename and explicit overwrite policy");
             }
             this.#assertCurrent();
+            assertFinalSymlinkRejected(path.join(this.#directory.realPath, basename), this.#rejectFinalSymlink);
+            this.#assertBeforeMutation?.();
             try {
                 if (overwrite) {
                     this.#binding.renameReplace(this.#parentFd, this.#name, this.#parentFd, basename);
@@ -262,6 +286,7 @@ class NativeStagedFile {
                 overwrite,
             });
             state.publication = receipt;
+            onPublished?.(receipt.staged.identity);
             const stagedMode = this.#assertNamed(basename);
             assertStagedDirectoryCurrent(this.#directory);
             // Keep contents private until the published name passes its identity
@@ -282,6 +307,8 @@ class NativeStagedFile {
             return receipt;
         }
         catch (error) {
+            if (error instanceof MutationAuthorityError)
+                throw error;
             // Closure rejects further use, not the recorded outcome of an earlier publication.
             const publication = this.#state.status === "closed"
                 ? this.#state.receipt.publication

package/dist/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAMzB,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,kBAAkB,CAAC;AAM1B,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAA6B,GAAG,IAAI,CAIjG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA4BlE;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAElE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CA0BpE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAOrF"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAMzB,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,kBAAkB,CAAC;AAM1B,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAA6B,GAAG,IAAI,CAIjG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA8BlE;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAElE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CA0BpE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAOrF"}

package/dist/path.js

@@ -49,7 +49,9 @@ export function isPathInside(root, target) {
         target.charCodeAt(0) === POSIX_SEPARATOR_CHAR_CODE &&
         !target.includes("/..") &&
         (target === root ||
-            (target.startsWith(root) && target.charCodeAt(root.length) === POSIX_SEPARATOR_CHAR_CODE))) {
+            (target.startsWith(root) &&
+                (root.charCodeAt(root.length - 1) === POSIX_SEPARATOR_CHAR_CODE ||
+                    target.charCodeAt(root.length) === POSIX_SEPARATOR_CHAR_CODE)))) {
         return true;
     }
     const resolvedRoot = path.resolve(root);

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

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

package/dist/permissions-windows.js

@@ -1,9 +1,9 @@
 import os from "node:os";
 import { getNativeBinding } from "./native.js";
-import { executePermissionCommand, formatPermissionErrorDetail, getPermissionCommandFailure, } from "./permission-exec.js";
+import { executePermissionCommand } from "./permission-exec.js";
 import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
-import { inspectWindowsOwner, resolveWindowsCurrentUserSid, resolveWindowsPrincipalSids, } from "./windows-owner.js";
+import { inspectWindowsOwner } from "./windows-owner.js";
 const INHERIT_FLAGS = new Set(["I", "OI", "CI", "IO", "NP"]);
 const WORLD_PRINCIPALS = new Set(["everyone", "users", "builtin\\users", "authenticated users", "nt authority\\authenticated users", "anonymous logon", "nt authority\\anonymous logon", "guests", "builtin\\guests", "interactive", "nt authority\\interactive", "network", "nt authority\\network", "local"]);
 const TRUSTED_BASE = new Set([
@@ -92,13 +92,7 @@ export async function inspectWindowsPermissions(params) {
         const error = `Windows owner inspection failed: ${owner.error}`;
         return { ...unverified, ownerError: owner.error, error, errorDetail: owner.errorDetail, errorCause: owner.errorCause };
     }
-    const acl = await inspectWindowsAcl(params.targetPath, {
-        env: params.opts?.env,
-        exec: params.opts?.exec,
-        currentUserSid: owner.currentUserSid,
-        principalSids: owner.principalSids,
-        principalTranslationFailed: owner.principalTranslationFailed,
-    });
+    const acl = summarizeWindowsOwnerAcl(owner);
     const ownerFields = {
         ...(owner.sid ? { ownerSid: owner.sid } : {}),
         ...(owner.trusted !== undefined ? { ownerTrusted: owner.trusted } : {}),
@@ -230,49 +224,45 @@ export function summarizeWindowsAcl(entries, env) {
     }
     return { trusted, untrustedWorld, untrustedGroup };
 }
-export async function inspectWindowsAcl(targetPath, opts) {
-    let command = "";
-    let startedAt = performance.now();
-    const exec = async (file, args) => {
-        command = file;
-        startedAt = performance.now();
-        return await (opts?.exec ?? defaultPermissionExec)(file, args);
-    };
-    try {
-        if (opts?.principalTranslationFailed)
-            throw new Error("Windows ACL principal SID translation failed");
-        const { stdout, stderr } = await exec(resolveWindowsSystemCommand("icacls.exe", opts?.env), [targetPath]);
-        let entries = parseIcaclsOutput(`${stdout}\n${stderr}`.trim(), targetPath);
-        if (!entries.length)
-            throw new Error("Windows ACL output could not be verified");
-        const unresolvedPrincipals = entries.filter((entry) => !entry.sid).map((entry) => entry.principal);
-        const principalSids = await resolveWindowsPrincipalSids({ principals: unresolvedPrincipals, known: opts?.principalSids, env: opts?.env, exec });
-        entries = entries.map((entry) => {
-            const sid = entry.sid ?? principalSids[entry.principal.toLowerCase()];
-            if (!sid)
-                throw new Error(`Windows ACL principal SID could not be verified: ${entry.principal}`);
-            return { ...entry, sid };
-        });
-        let currentUserSid = normalizeSid(opts?.currentUserSid ?? "");
-        let effectiveEnv = currentUserSid ? { USERSID: currentUserSid } : undefined;
-        let { trusted, untrustedWorld, untrustedGroup } = summarizeWindowsAcl(entries, effectiveEnv);
-        if (!currentUserSid && untrustedGroup.some((entry) => entry.sid && !TRUSTED_SIDS.has(entry.sid))) {
-            currentUserSid = (await resolveWindowsCurrentUserSid({ exec, env: opts?.env })) ?? "";
-            if (currentUserSid) {
-                effectiveEnv = { USERSID: currentUserSid };
-                ({ trusted, untrustedWorld, untrustedGroup } = summarizeWindowsAcl(entries, effectiveEnv));
-            }
-        }
-        return { ok: true, entries, trusted, untrustedWorld, untrustedGroup };
-    }
-    catch (err) {
+const MASK_RIGHTS = [
+    [0x1000_0000, "GA"], [0x8000_0000, "GR"], [0x4000_0000, "GW"], [0x2000_0000, "GE"],
+    [0x0001_0000, "D"], [0x0002_0000, "RC"], [0x0004_0000, "WDAC"], [0x0008_0000, "WO"],
+    [0x0010_0000, "S"], [0x0001, "RD"], [0x0002, "WD"], [0x0004, "AD"],
+    [0x0008, "REA"], [0x0010, "WEA"], [0x0020, "X"], [0x0040, "DC"], [0x0080, "RA"], [0x0100, "WA"],
+];
+function summarizeWindowsOwnerAcl(owner) {
+    const error = owner.error ?? owner.aclError;
+    if (error || owner.daclPresent === undefined || !owner.aces || !owner.currentUserSid) {
         return {
             ok: false, entries: [], trusted: [], untrustedWorld: [], untrustedGroup: [],
-            error: formatPermissionErrorDetail(String(err)),
-            errorDetail: getPermissionCommandFailure(err, command, performance.now() - startedAt),
-            errorCause: err,
+            error: error ?? "Windows ACL query returned incomplete descriptor data",
+            errorDetail: owner.errorDetail, errorCause: owner.errorCause,
         };
     }
+    // A null DACL grants everyone full access; an empty DACL grants nothing.
+    const grants = owner.daclPresent ? owner.aces : [{ sid: "s-1-1-0", mask: 0x001f_01ff, deny: false, inheritOnly: false }];
+    const entries = grants.filter(ace => !ace.deny && !ace.inheritOnly).map(ace => {
+        const rights = ace.mask === 0x001f_01ff ? ["F"] : MASK_RIGHTS.filter(([mask]) => (ace.mask & mask) !== 0).map(([, name]) => name);
+        return {
+            principal: ace.sid, sid: ace.sid, rights, rawRights: "(" + rights.join(",") + ")",
+            // Retain the coarse policy's conservative treatment of read-control and
+            // mutation rights. Denies do not subtract grants or claim effective access.
+            canRead: (ace.mask & 0x9002_0089) !== 0,
+            canWrite: (ace.mask & 0x500d_0156) !== 0,
+        };
+    });
+    return { ok: true, entries, ...summarizeWindowsAcl(entries, { USERSID: owner.currentUserSid }) };
+}
+export async function inspectWindowsAcl(targetPath, opts) {
+    if (opts?.principalTranslationFailed) {
+        const error = new Error("Windows ACL principal SID translation failed");
+        return summarizeWindowsOwnerAcl({ error: String(error), errorCause: error });
+    }
+    const owner = await inspectWindowsOwner({ targetPath, env: opts?.env, exec: opts?.exec ?? defaultPermissionExec });
+    return summarizeWindowsOwnerAcl({
+        ...owner,
+        currentUserSid: normalizeSid(opts?.currentUserSid ?? "") || owner.currentUserSid,
+    });
 }
 export function formatWindowsAclSummary(summary) {
     if (!summary.ok)

package/dist/pinned-operation.js

@@ -27,7 +27,7 @@ function validatePinnedRelativePath(relativePath) {
         relativePath.startsWith("..\\")) {
         throw new FsSafeError("invalid-path", "relative path must not escape root");
     }
-    for (const segment of relativePath.split("/")) {
+    for (const segment of relativePath.split(process.platform === "win32" ? /[\\/]/ : "/")) {
         if (segment === "..") {
             throw new FsSafeError("invalid-path", "relative path must not contain '..'");
         }

package/dist/pinned-write.d.ts

@@ -1,6 +1,7 @@
 import type { Readable } from "node:stream";
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
+import { type CopyFileInput } from "./copy-file-input.js";
 export type PinnedWriteInput = {
     kind: "buffer";
     data: string | Buffer;
@@ -8,7 +9,7 @@ export type PinnedWriteInput = {
 } | {
     kind: "stream";
     stream: Readable;
-};
+} | CopyFileInput;
 export type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
 export type PublishedWriteIdentity = Readonly<{
     dev: bigint;
@@ -22,10 +23,13 @@ export type PinnedWriteParams = {
     mode: number;
     sync?: boolean;
     overwrite?: boolean;
+    assertBeforeMutation?: () => void;
+    rejectFinalSymlink?: boolean;
     maxBytes?: number;
     input: PinnedWriteInput;
     rootIdentity?: FileIdentityStat;
     onRenameIdentityMismatch?: "verify-content";
+    onPublished?: (identity: PublishedWriteIdentity) => void;
     verifyPublished?: (fd: number, identity: PublishedWriteIdentity, parentGuard: AnyAsyncDirectoryGuard) => Promise<void>;
 };
 export declare function runPinnedWriteHelper(params: PinnedWriteParams): Promise<FileIdentityStat>;

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

@@ -1 +1 @@
-{"version":3,"file":"pinned-write.d.ts","sourceRoot":"","sources":["../src/pinned-write.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAA4F,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG7J,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAY3D,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAsDzC,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,0BAA0B,CAAC;AAEzE,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE5E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;IACxB,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;IAE5C,eAAe,CAAC,EAAE,CAChB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,sBAAsB,EAChC,WAAW,EAAE,sBAAsB,KAChC,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgB/F;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,iBAAiB,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC,GACA,OAAO,CAAC,gBAAgB,CAAC,CA2B3B"}
+{"version":3,"file":"pinned-write.d.ts","sourceRoot":"","sources":["../src/pinned-write.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAA4F,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG7J,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAa3D,OAAO,EAAE,KAAK,aAAa,EAAqB,MAAM,sBAAsB,CAAC;AAG7E,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpC,aAAa,CAAC;AA4ClB,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,0BAA0B,CAAC;AAEzE,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE5E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;IACxB,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;IAC5C,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,CAAC;IAEzD,eAAe,CAAC,EAAE,CAChB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,sBAAsB,EAChC,WAAW,EAAE,sBAAsB,KAChC,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgB/F;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,iBAAiB,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC,GACA,OAAO,CAAC,gBAAgB,CAAC,CA2B3B"}

package/dist/pinned-write.js

@@ -17,6 +17,10 @@ import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { cleanupPinnedFilePath } from "./replace-file-temp-owner.js";
 import { withSidecarLock } from "./sidecar-lock.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
+import { writeAllToFile } from "./write-file-handle.js";
+import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { writeCopyFileToFd } from "./copy-file-input.js";
+import { publishCopyStage } from "./publish-copy-stage.js";
 function byteLength(input, encoding) {
     return typeof input === "string"
         ? Buffer.byteLength(input, encoding ?? "utf8")
@@ -36,20 +40,13 @@ function assertWithinMaxBytes(bytes, maxBytes) {
         throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
     }
 }
-async function writeStreamToHandle(stream, handle, maxBytes) {
+async function writeStreamToHandle(stream, handle, maxBytes, assertBeforeMutation) {
     let bytes = 0;
     for await (const chunk of stream) {
         const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         bytes += buffer.byteLength;
         assertWithinMaxBytes(bytes, maxBytes);
-        let offset = 0;
-        while (offset < buffer.byteLength) {
-            const { bytesWritten } = await handle.write(buffer, offset, buffer.byteLength - offset);
-            if (bytesWritten <= 0) {
-                throw new FsSafeError("helper-failed", "fallback stream write made no progress");
-            }
-            offset += bytesWritten;
-        }
+        await writeAllToFile(handle, buffer, { assertBeforeMutation });
     }
 }
 export async function runPinnedWriteHelper(params) {
@@ -95,7 +92,6 @@ async function runPinnedWriteFallback(params) {
         ? { dev: params.rootIdentity.dev, ino: params.rootIdentity.ino } : undefined;
     if (exactRoot)
         await inspectDirectoryIdentity(params.rootPath, exactRoot);
-    const guardOptions = { bigint: exactRoot !== undefined };
     let parentPath = params.relativeParentPath
         ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
         : params.rootPath;
@@ -107,15 +103,23 @@ async function runPinnedWriteFallback(params) {
         parentPath = await mkdirPathComponentsWithGuards({
             rootReal: params.rootPath,
             targetPath: parentPath,
+            assertBeforeMutation: params.assertBeforeMutation,
             beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
         });
     }
     const parentGuard = params.mkdir
-        ? await createAsyncDirectoryGuard(parentPath, guardOptions)
-        : await createNearestExistingDirectoryGuard(params.rootPath, parentPath, guardOptions);
+        ? await createAsyncDirectoryGuard(parentPath, { bigint: true })
+        : await createNearestExistingDirectoryGuard(params.rootPath, parentPath, { bigint: true });
     const targetPath = path.join(parentPath, params.basename);
-    if (params.overwrite === false) {
-        const handle = await withAsyncDirectoryGuards([parentGuard], async () => await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, params.mode), {
+    if (params.overwrite === false && params.input.kind !== "file") {
+        const assertBeforeMutation = () => {
+            assertFinalSymlinkRejected(targetPath, params.rejectFinalSymlink);
+            params.assertBeforeMutation?.();
+        };
+        const handle = await withAsyncDirectoryGuards([parentGuard], async () => {
+            assertBeforeMutation();
+            return await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, params.mode);
+        }, {
             onPostGuardFailure: async (openedHandle) => {
                 // The parent failed verification, so targetPath may now resolve
                 // somewhere else. Close the fd, but do not clean up by path.
@@ -129,15 +133,12 @@ async function runPinnedWriteFallback(params) {
             createdIdentity = verificationIdentity;
             if (params.input.kind === "buffer") {
                 assertWithinMaxBytes(byteLength(params.input.data, params.input.encoding), params.maxBytes);
-                if (typeof params.input.data === "string") {
-                    await handle.writeFile(params.input.data, params.input.encoding ?? "utf8");
-                }
-                else {
-                    await handle.writeFile(params.input.data);
-                }
+                await writeAllToFile(handle, params.input.data, {
+                    encoding: params.input.encoding, assertBeforeMutation,
+                });
             }
             else {
-                await writeStreamToHandle(params.input.stream, handle, params.maxBytes);
+                await writeStreamToHandle(params.input.stream, handle, params.maxBytes, assertBeforeMutation);
             }
             // Content writes may clear set-ID bits; finalize them through the owned fd.
             await handle.chmod(params.mode);
@@ -176,20 +177,21 @@ async function runPinnedWriteFallback(params) {
     let readHandle;
     let renamed = false;
     try {
+        params.assertBeforeMutation?.();
         handle = await fs.open(tempPath, tempFlags, params.mode);
         let verificationIdentity = fsSync.fstatSync(handle.fd, { bigint: true });
         tempIdentity = verificationIdentity;
         if (params.input.kind === "buffer") {
             assertWithinMaxBytes(byteLength(params.input.data, params.input.encoding), params.maxBytes);
-            if (typeof params.input.data === "string") {
-                await handle.writeFile(params.input.data, params.input.encoding ?? "utf8");
-            }
-            else {
-                await handle.writeFile(params.input.data);
-            }
+            await writeAllToFile(handle, params.input.data, {
+                encoding: params.input.encoding, assertBeforeMutation: params.assertBeforeMutation,
+            });
+        }
+        else if (params.input.kind === "file") {
+            await writeCopyFileToFd(handle.fd, params.input, params.maxBytes, params.assertBeforeMutation);
         }
         else {
-            await writeStreamToHandle(params.input.stream, handle, params.maxBytes);
+            await writeStreamToHandle(params.input.stream, handle, params.maxBytes, params.assertBeforeMutation);
         }
         tempStat = fsSync.fstatSync(handle.fd);
         const tempPathStat = fsSync.lstatSync(tempPath);
@@ -200,10 +202,28 @@ async function runPinnedWriteFallback(params) {
         await handle.chmod(params.mode);
         if (params.sync !== false)
             await syncFileBestEffort(handle);
+        if (params.input.kind === "file")
+            await params.input.verifySource();
         let verifiedIdentity = expectedTempStat;
         await withAsyncDirectoryGuards([parentGuard], async () => {
-            await fs.rename(tempPath, targetPath);
-            renamed = true;
+            assertFinalSymlinkRejected(targetPath, params.rejectFinalSymlink);
+            if (params.overwrite === false) {
+                publishCopyStage({
+                    temporaryPath: tempPath, targetPath, fd: handle.fd,
+                    identity: tempIdentity, parentGuard,
+                    assertBeforeMutation: params.assertBeforeMutation,
+                    onPublished: (identity) => {
+                        renamed = true;
+                        params.onPublished?.(identity);
+                    },
+                });
+            }
+            else {
+                params.assertBeforeMutation?.();
+                await fs.rename(tempPath, targetPath);
+                renamed = true;
+                params.onPublished?.(verificationIdentity);
+            }
             await getFsSafeTestHooks()?.afterPinnedWriteFallbackRename?.(targetPath);
             if (params.sync !== false)
                 await syncDirectoryBestEffort(parentPath);

package/dist/positional-read.d.ts

@@ -0,0 +1,9 @@
+import type { FileHandle } from "node:fs/promises";
+export type ReadFileWindowOptions = {
+    signal?: AbortSignal;
+};
+/** Fills a caller-owned buffer from an explicit position, stopping at EOF. */
+export declare function readFileWindowFully(handle: FileHandle, buffer: Buffer, position: number, { signal }?: ReadFileWindowOptions): Promise<number>;
+/** Synchronous positional read; neither variant advances or closes its descriptor. */
+export declare function readFileWindowFullySync(fd: number, buffer: Buffer, position: number): number;
+//# sourceMappingURL=positional-read.d.ts.map

package/dist/positional-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"positional-read.d.ts","sourceRoot":"","sources":["../src/positional-read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AASF,8EAA8E;AAC9E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,EAAE,MAAM,EAAE,GAAE,qBAA0B,GACrC,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW5F"}

package/dist/positional-read.js

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+// Node's synchronous read length is a signed 32-bit value on supported runtimes.
+const MAX_READ_BYTES = 0x7fffffff;
+function validateWindow(buffer, position) {
+    if (!Number.isSafeInteger(position) || position < 0 ||
+        !Number.isSafeInteger(position + buffer.length)) {
+        throw new RangeError("read position and window end must be non-negative safe integers");
+    }
+}
+/** Fills a caller-owned buffer from an explicit position, stopping at EOF. */
+export async function readFileWindowFully(handle, buffer, position, { signal } = {}) {
+    validateWindow(buffer, position);
+    signal?.throwIfAborted();
+    let total = 0;
+    while (total < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, total, Math.min(buffer.length - total, MAX_READ_BYTES), position + total);
+        // Settle the pending read before cancellation lets the caller reuse its buffer or handle.
+        signal?.throwIfAborted();
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+    }
+    return total;
+}
+/** Synchronous positional read; neither variant advances or closes its descriptor. */
+export function readFileWindowFullySync(fd, buffer, position) {
+    validateWindow(buffer, position);
+    let total = 0;
+    while (total < buffer.length) {
+        const bytesRead = fs.readSync(fd, buffer, total, Math.min(buffer.length - total, MAX_READ_BYTES), position + total);
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+    }
+    return total;
+}

package/dist/publish-copy-stage.d.ts

@@ -0,0 +1,13 @@
+import { type BigIntStats } from "node:fs";
+import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { PublishedWriteIdentity } from "./pinned-write.js";
+export declare function publishCopyStage(params: {
+    temporaryPath: string;
+    targetPath: string;
+    fd: number;
+    identity: BigIntStats;
+    parentGuard: AnyAsyncDirectoryGuard;
+    assertBeforeMutation?: () => void;
+    onPublished?: (identity: PublishedWriteIdentity) => void;
+}): void;
+//# sourceMappingURL=publish-copy-stage.d.ts.map

package/dist/publish-copy-stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-copy-stage.d.ts","sourceRoot":"","sources":["../src/publish-copy-stage.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAGnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAIhE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,WAAW,CAAC;IACtB,WAAW,EAAE,sBAAsB,CAAC;IACpC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,CAAC;CAC1D,GAAG,IAAI,CAqCP"}

package/dist/publish-copy-stage.js

@@ -0,0 +1,47 @@
+import fs, {} from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+// Node has no portable no-replace rename. Link only our completed private stage,
+// then unlink it in the same JS turn so local readers never observe two names.
+export function publishCopyStage(params) {
+    const { identity, temporaryPath, targetPath } = params;
+    const staged = fs.lstatSync(temporaryPath, { bigint: true });
+    const opened = fs.fstatSync(params.fd, { bigint: true });
+    if (!staged.isFile() || staged.isSymbolicLink() || staged.nlink !== 1n ||
+        !sameFileIdentityForCleanup(staged, identity) ||
+        !sameFileIdentityForCleanup(opened, identity)) {
+        throw new FsSafeError("path-mismatch", "exclusive copy stage changed before publication");
+    }
+    params.assertBeforeMutation?.();
+    fs.linkSync(temporaryPath, targetPath);
+    let observerRejected = false;
+    let observerError;
+    try {
+        params.onPublished?.(identity);
+    }
+    catch (error) {
+        observerRejected = true;
+        observerError = error;
+    }
+    try {
+        const parent = fs.lstatSync(path.dirname(temporaryPath), { bigint: true });
+        const current = fs.lstatSync(temporaryPath, { bigint: true });
+        if (parent.isSymbolicLink() || !parent.isDirectory() ||
+            !sameFileIdentityForCleanup(parent, params.parentGuard.stat) ||
+            current.isSymbolicLink() || !current.isFile() ||
+            !sameFileIdentityForCleanup(current, identity)) {
+            throw new FsSafeError("path-mismatch", "published copy temporary name changed before cleanup");
+        }
+        // This removes the stage's name, never the published destination or source.
+        fs.unlinkSync(temporaryPath);
+    }
+    catch (error) {
+        throw new FsSafeError("helper-failed", "published copy temporary cleanup failed", {
+            cause: observerRejected ? new AggregateError([observerError, error], "observer and cleanup failed") : error,
+            details: { publication: "published", path: targetPath, dev: identity.dev, ino: identity.ino, cleanup: "failed" },
+        });
+    }
+    if (observerRejected)
+        throw observerError;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"publish-file.d.ts","sourceRoot":"","sources":["../src/publish-file.ts"],"names":[],"mappings":"AACA,OAAe,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAI/D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAML,KAAK,qCAAqC,EAC3C,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,2BAA2B,EAC3B,wCAAwC,EACxC,kCAAkC,EAClC,gCAAgC,EAChC,qCAAqC,GACtC,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,4BAA4B,GACpC,cAAc,GACd,eAAe,GACf,kBAAkB,CAAC;AAEvB,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;IAC3D,QAAQ,EAAE,KAAK,CAAC;IAChB,aAAa,EAAE,oBAAoB,CAAC;CACrC,CAAC;AAkBF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AA0ND,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,gBAAgB,CAAC;IAC1C,QAAQ,EAAE,4BAA4B,CAAC;IACvC,aAAa,CAAC,EAAE,qCAAqC,CAAC;IACtD,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4MtC"}
+{"version":3,"file":"publish-file.d.ts","sourceRoot":"","sources":["../src/publish-file.ts"],"names":[],"mappings":"AACA,OAAe,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAI/D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAML,KAAK,qCAAqC,EAC3C,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,2BAA2B,EAC3B,wCAAwC,EACxC,kCAAkC,EAClC,gCAAgC,EAChC,qCAAqC,GACtC,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,4BAA4B,GACpC,cAAc,GACd,eAAe,GACf,kBAAkB,CAAC;AAEvB,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;IAC3D,QAAQ,EAAE,KAAK,CAAC;IAChB,aAAa,EAAE,oBAAoB,CAAC;CACrC,CAAC;AAkBF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AA2ND,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,gBAAgB,CAAC;IAC1C,QAAQ,EAAE,4BAA4B,CAAC;IACvC,aAAa,CAAC,EAAE,qCAAqC,CAAC;IACtD,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4MtC"}

package/dist/publish-file.js

@@ -90,9 +90,9 @@ async function copyPinnedSource(params) {
                 throw error;
             }
             let target;
-            let createdIdentity = fsSync.fstatSync(nativeFd, { bigint: true });
-            rememberCreatedTarget(params.failure, createdIdentity, "copy-verify");
             try {
+                let createdIdentity = fsSync.fstatSync(nativeFd, { bigint: true });
+                rememberCreatedTarget(params.failure, createdIdentity, "copy-verify");
                 fsSync.fchmodSync(nativeFd, 0o600);
                 createdIdentity = fsSync.fstatSync(nativeFd, { bigint: true });
                 await getFsSafeTestHooks()?.afterPublishTargetCreated?.("exclusive-copy", params.targetPath, createdIdentity);
@@ -106,8 +106,9 @@ async function copyPinnedSource(params) {
                     throw new FsSafeError("path-mismatch", "native publication target changed after copy");
                 }
                 const hashed = await hashFileHandle(target, params.native);
-                fsSync.closeSync(nativeFd);
+                const completedFd = nativeFd;
                 nativeFd = undefined;
+                fsSync.closeSync(completedFd);
                 return {
                     handle: target,
                     exactIdentity: opened,
@@ -126,9 +127,9 @@ async function copyPinnedSource(params) {
         }
     }
     const target = await fs.open(params.targetPath, "wx+", 0o600);
-    const createdIdentity = fsSync.fstatSync(target.fd, { bigint: true });
-    rememberCreatedTarget(params.failure, createdIdentity, "copy-verify");
     try {
+        const createdIdentity = fsSync.fstatSync(target.fd, { bigint: true });
+        rememberCreatedTarget(params.failure, createdIdentity, "copy-verify");
         await target.chmod(0o600);
         const exactIdentity = fsSync.fstatSync(target.fd, { bigint: true });
         await getFsSafeTestHooks()?.afterPublishTargetCreated?.("exclusive-copy", params.targetPath, exactIdentity);