@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/directory-guard.js

@@ -5,61 +5,102 @@ import { sameFileIdentity } from "./file-identity.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { isNotFoundPathError } from "./path.js";
 import { directoryComponentNotDirectoryError } from "./root-errors.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { realpathSync } from "./realpath.js";
+import { directoryEntryPath } from "./directory-entry-path.js";
+import { assertStatObservationSync, inspectStatObservationSync, } from "./stat-observation.js";
 export async function readDirectoryIdentity(dir) {
     const guard = await createAsyncDirectoryGuard(dir, { bigint: true });
     return Object.freeze({ dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath });
 }
 export function assertDirectoryIdentitySync(observedPath, expected) {
-    inspectDirectoryIdentitySync(observedPath, expected);
-    if (expected.realPath !== undefined && realpathSync.native(observedPath) !== expected.realPath) {
+    const operationPath = directoryOperationPath(observedPath);
+    const expectedDev = expected.dev;
+    const expectedIno = expected.ino;
+    const expectedRealPath = expected.realPath;
+    if (expectedRealPath !== undefined)
+        assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    inspectDirectoryIdentityAtPathSync(operationPath, { dev: expectedDev, ino: expectedIno });
+    if (expectedRealPath === undefined)
+        return;
+    const realPath = realpathSync.native(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if (realPath !== expectedRealPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
 }
 export async function createAsyncDirectoryGuard(dir, options) {
-    const stat = options?.bigint ? inspectDirectoryIdentitySync(dir) : fsSync.lstatSync(dir);
+    const operationPath = directoryOperationPath(dir);
+    const stat = options?.bigint
+        ? inspectDirectoryIdentityAtPathSync(operationPath, undefined, options.initial)
+        : fsSync.lstatSync(operationPath);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    return { dir, realPath: realpathSync.native(dir), stat };
+    const realPath = realpathSync.native(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    return { dir, realPath, stat };
 }
 export async function assertAsyncDirectoryGuard(guard) {
-    if (typeof guard.stat.dev === "bigint" && typeof guard.stat.ino === "bigint") {
-        assertDirectoryIdentitySync(guard.dir, { dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath });
-        return;
-    }
-    const stat = fsSync.lstatSync(guard.dir);
+    const dir = guard.dir;
+    const operationPath = directoryOperationPath(dir);
+    const expectedRealPath = guard.realPath;
+    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    const expectedStat = guard.stat;
+    const expectedIdentity = { dev: expectedStat.dev, ino: expectedStat.ino };
+    const stat = typeof expectedIdentity.dev === "bigint" && typeof expectedIdentity.ino === "bigint"
+        ? inspectDirectoryIdentityAtPathSync(operationPath, {
+            dev: expectedIdentity.dev,
+            ino: expectedIdentity.ino,
+        })
+        : fsSync.lstatSync(operationPath);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    if (!sameFileIdentity(stat, guard.stat) || realpathSync.native(guard.dir) !== guard.realPath) {
+    if (!sameFileIdentity(stat, expectedIdentity)) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+    const realPath = realpathSync.native(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if (realPath !== expectedRealPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
 }
 export function createSyncDirectoryGuard(dir) {
-    const stat = fsSync.lstatSync(dir);
+    const operationPath = directoryOperationPath(dir);
+    const stat = fsSync.lstatSync(operationPath);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    return { dir, realPath: realpathSync(dir), stat };
+    const realPath = realpathSync(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    return { dir, realPath, stat };
 }
 export function assertSyncDirectoryGuard(guard) {
-    if (typeof guard.stat.dev === "bigint" && typeof guard.stat.ino === "bigint") {
-        assertDirectoryIdentitySync(guard.dir, { dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath });
-        return;
-    }
-    const stat = fsSync.lstatSync(guard.dir);
+    const dir = guard.dir;
+    const operationPath = directoryOperationPath(dir);
+    const expectedRealPath = guard.realPath;
+    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    const expectedStat = guard.stat;
+    const expectedIdentity = { dev: expectedStat.dev, ino: expectedStat.ino };
+    const stat = typeof expectedIdentity.dev === "bigint" && typeof expectedIdentity.ino === "bigint"
+        ? inspectDirectoryIdentityAtPathSync(operationPath, { dev: expectedIdentity.dev, ino: expectedIdentity.ino })
+        : fsSync.lstatSync(operationPath);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    const realPath = realpathSync(guard.dir);
-    if (!sameFileIdentity(stat, guard.stat) || realPath !== guard.realPath) {
+    const realPath = typeof expectedIdentity.ino === "bigint"
+        ? realpathSync.native(operationPath) : realpathSync(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if (!sameFileIdentity(stat, expectedIdentity) || realPath !== expectedRealPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
 }
 export async function createNearestExistingDirectoryGuard(rootReal, targetPath, options = { bigint: false }) {
-    let current = path.resolve(targetPath);
-    const root = path.resolve(rootReal);
+    assertNoWindowsPathAlias(rootReal, "filesystem");
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    let current = resolvePathPreservingWindowsRoot(targetPath);
+    const root = resolvePathPreservingWindowsRoot(rootReal);
     while (current !== root) {
         try {
             return await createAsyncDirectoryGuard(current, options);
@@ -74,8 +115,10 @@ export async function createNearestExistingDirectoryGuard(rootReal, targetPath,
     return await createAsyncDirectoryGuard(root, options);
 }
 export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
-    let current = path.resolve(targetPath);
-    const root = path.resolve(rootReal);
+    assertNoWindowsPathAlias(rootReal, "filesystem");
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    let current = resolvePathPreservingWindowsRoot(targetPath);
+    const root = resolvePathPreservingWindowsRoot(rootReal);
     while (current !== root) {
         try {
             return createSyncDirectoryGuard(current);
@@ -91,34 +134,77 @@ export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
 }
 // Recovery receipts must retain every identity bit, including on Windows.
 export async function inspectDirectoryIdentity(dir, expected) {
-    return inspectDirectoryIdentitySync(dir, expected);
-}
-function directoryEntryPath(dir) {
-    const windows = process.platform === "win32";
-    if (typeof dir === "string") {
-        const last = dir[dir.length - 1];
-        if (last !== "/" && (!windows || last !== "\\"))
-            return dir;
-    }
-    let rootLength = (windows ? path.win32 : path.posix).parse(dir).root.length;
-    if (windows && /^[\\/]{2}[?.][\\/]UNC[\\/]/i.test(dir)) {
-        // Node parses the namespace prefix as the root; retain the complete UNC share instead.
-        const uncRoot = path.win32.parse(`\\\\${dir.slice(8)}`).root;
-        if (uncRoot.length > 1)
-            rootLength = Math.max(rootLength, uncRoot.length + 6);
-    }
-    let end = dir.length;
-    while (end > rootLength && (dir[end - 1] === "/" || (windows && dir[end - 1] === "\\")))
-        end--;
-    return end === rootLength || end === dir.length ? dir : dir.slice(0, end);
-}
-export function inspectDirectoryIdentitySync(dir, expected) {
-    // A trailing separator makes lstat follow a final directory symlink.
-    const entryPath = directoryEntryPath(dir);
+    const operationPath = directoryOperationPath(dir);
+    const expectedIdentity = expected === undefined
+        ? undefined
+        : { dev: expected.dev, ino: expected.ino };
+    return inspectDirectoryIdentityAtPathSync(operationPath, expectedIdentity);
+}
+function directoryOperationPath(dir) {
+    assertNoWindowsPathAlias(dir, "filesystem");
+    return pathForWindowsFilesystem(directoryEntryPath(dir));
+}
+export function observeDirectoryIdentitySync(dir, options) {
+    const entryPath = directoryOperationPath(dir);
+    const stat = options?.bigint
+        ? fsSync.lstatSync(entryPath, { bigint: true })
+        : fsSync.lstatSync(entryPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw directoryComponentNotDirectoryError();
+    return stat;
+}
+export function inspectDirectoryIdentitySync(dir, expected, initial, platform = process.platform) {
+    const operationPath = directoryOperationPath(dir);
+    const expectedIdentity = expected === undefined
+        ? undefined
+        : { dev: expected.dev, ino: expected.ino };
+    return inspectDirectoryIdentityAtPathSync(operationPath, expectedIdentity, initial, platform);
+}
+function inspectDirectoryIdentityAtPathSync(operationPath, expected, initial, platform = process.platform) {
     return inspectFileIdentitySync(() => {
-        const stat = fsSync.lstatSync(entryPath, { bigint: true });
+        // Traversal can supply the first exact observation. A bounded retry still
+        // uses the admitted operation path and retains every known identity bit.
+        const stat = initial ?? fsSync.lstatSync(operationPath, { bigint: true });
+        initial = undefined;
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        return stat;
+    }, expected, platform);
+}
+export function extendDirectoryObservationGuard(observation, dir, realPath) {
+    const guard = observation;
+    guard.dir = dir;
+    guard.realPath = realPath;
+    return guard;
+}
+// Only stat/list receipts use this metadata fast path. Recovery and publication
+// callers retain the BigIntStats contract of inspectDirectoryIdentitySync.
+export function inspectDirectoryObservationSync(dir, expected) {
+    const entryPath = directoryOperationPath(dir);
+    return inspectStatObservationSync(bigint => {
+        const stat = bigint ? fsSync.lstatSync(entryPath, { bigint: true }) : fsSync.lstatSync(entryPath);
         if (stat.isSymbolicLink() || !stat.isDirectory())
             throw directoryComponentNotDirectoryError();
         return stat;
     }, expected);
 }
+export function assertDirectoryObservationSync(dir, expected) {
+    const entryPath = directoryOperationPath(dir);
+    return assertStatObservationSync(bigint => {
+        const stat = bigint ? fsSync.lstatSync(entryPath, { bigint: true }) : fsSync.lstatSync(entryPath);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        return stat;
+    }, expected);
+}
+export function assertDirectoryObservationGuardSync(guard) {
+    const dir = guard.dir;
+    const expectedRealPath = guard.realPath;
+    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    assertDirectoryObservationSync(dir, guard.identity);
+    const realPath = realpathSync.native(directoryOperationPath(dir));
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if (realPath !== expectedRealPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}

package/dist/directory-mode-node.d.ts

@@ -1,8 +1,20 @@
 import { type BigIntStats } from "node:fs";
 import { type DirectoryModeOwner } from "./directory-mode-owner.js";
+export declare function nodeDirectorySearchOnlyFlags(): {
+    flags: number;
+    proc: boolean;
+} | undefined;
 /** Real Node only: injected filesystem adapters must retain descriptor-chmod semantics. */
 export declare function pinNodeDirectoryForMode(dirPath: string, options?: {
     expectedIdentity?: BigIntStats;
     ownerUid?: number;
 }): Promise<DirectoryModeOwner>;
+/** Synchronous counterpart with the same no-follow, identity, and owner checks. */
+export declare function pinNodeDirectoryForModeSync(dirPath: string, options?: {
+    expectedIdentity?: BigIntStats;
+    ownerUid?: number;
+}): {
+    apply(mode: number, check?: () => void): void;
+    close(): void;
+};
 //# sourceMappingURL=directory-mode-node.d.ts.map

package/dist/directory-mode-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"directory-mode-node.d.ts","sourceRoot":"","sources":["../src/directory-mode-node.ts"],"names":[],"mappings":"AAAA,OAAe,EAAa,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAK9D,OAAO,EAA0C,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAW5G,2FAA2F;AAC3F,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,OAAO,CAAC,kBAAkB,CAAC,CAsE7B"}
+{"version":3,"file":"directory-mode-node.d.ts","sourceRoot":"","sources":["../src/directory-mode-node.ts"],"names":[],"mappings":"AAAA,OAAe,EAAa,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAK9D,OAAO,EAA0C,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE5G,wBAAgB,4BAA4B,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAO3F;AAED,2FAA2F;AAC3F,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,OAAO,CAAC,kBAAkB,CAAC,CAsE7B;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE;IAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE,CAsFlE"}

package/dist/directory-mode-node.js

@@ -1,10 +1,10 @@
 import fsSync, { constants } from "node:fs";
 import fs from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
-import { inspectDirectoryIdentity } from "./directory-guard.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertOwnedDirectory, ownDirectoryMode } from "./directory-mode-owner.js";
-function searchOnlyFlags() {
+export function nodeDirectorySearchOnlyFlags() {
     if (process.arch !== "x64" && process.arch !== "arm64")
         return undefined;
     // Darwin SDK O_SEARCH = O_EXEC (0x40000000) | O_DIRECTORY, on x64/arm64.
@@ -41,7 +41,7 @@ export async function pinNodeDirectoryForMode(dirPath, options = {}) {
     const handle = await fs.open(dirPath, constants.O_RDONLY | flags).catch(async (error) => {
         if (error.code !== "EACCES")
             throw error;
-        const route = searchOnlyFlags();
+        const route = nodeDirectorySearchOnlyFlags();
         if (!route)
             throw error;
         proc = route.proc;
@@ -91,3 +91,101 @@ export async function pinNodeDirectoryForMode(dirPath, options = {}) {
         throw error;
     }
 }
+/** Synchronous counterpart with the same no-follow, identity, and owner checks. */
+export function pinNodeDirectoryForModeSync(dirPath, options = {}) {
+    const expected = inspectDirectoryIdentitySync(dirPath, options.expectedIdentity);
+    const assertOwner = (stat) => {
+        if (options.ownerUid !== undefined && stat.uid !== BigInt(options.ownerUid)) {
+            throw new FsSafeError("not-owned", "directory mode target must retain its expected owner");
+        }
+    };
+    assertOwner(expected);
+    if (process.platform === "win32") {
+        return {
+            apply: (_mode, check) => {
+                check?.();
+                assertOwner(inspectDirectoryIdentitySync(dirPath, expected));
+                check?.();
+            },
+            close: () => undefined,
+        };
+    }
+    if ([constants.O_DIRECTORY, constants.O_NOFOLLOW, constants.O_NONBLOCK, constants.O_RDONLY]
+        .some((flag) => typeof flag !== "number")) {
+        throw new FsSafeError("helper-unavailable", "no-follow directory mode descriptors are unavailable");
+    }
+    const flags = constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    let fd;
+    let proc = false;
+    try {
+        fd = fsSync.openSync(dirPath, constants.O_RDONLY | flags);
+    }
+    catch (error) {
+        if (error.code !== "EACCES")
+            throw error;
+        const route = nodeDirectorySearchOnlyFlags();
+        if (!route)
+            throw error;
+        proc = route.proc;
+        fd = fsSync.openSync(dirPath, route.flags | flags);
+    }
+    let closed = false;
+    const inspect = () => {
+        if (closed)
+            throw new FsSafeError("path-mismatch", "directory mode descriptor is closed");
+        const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), expected);
+        assertOwnedDirectory(expected, stat);
+        assertOwner(stat);
+        inspectDirectoryIdentitySync(dirPath, expected);
+        return Number(stat.mode & 4095n);
+    };
+    const procPath = `/proc/self/fd/${fd}`;
+    const assertProcAuthority = () => {
+        if (fsSync.statfsSync("/proc/self/fd", { bigint: true }).type !== 0x9fa0n) {
+            throw new FsSafeError("path-mismatch", "directory mode requires a trusted procfs fd namespace");
+        }
+        const opened = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), expected);
+        const followed = inspectFileIdentitySync(() => fsSync.statSync(procPath, { bigint: true }), expected);
+        assertOwnedDirectory(opened, followed);
+        assertOwner(opened);
+        assertOwner(followed);
+    };
+    try {
+        inspect();
+        return {
+            apply: (mode, check) => {
+                mode &= 0o7777;
+                check?.();
+                const currentMode = inspect();
+                check?.();
+                if (currentMode !== mode) {
+                    if (proc)
+                        assertProcAuthority();
+                    check?.();
+                    inspect();
+                    if (proc)
+                        fsSync.chmodSync(procPath, mode);
+                    else
+                        fsSync.fchmodSync(fd, mode);
+                    if (proc)
+                        assertProcAuthority();
+                }
+                const finalMode = inspect();
+                check?.();
+                if (finalMode !== mode) {
+                    throw new FsSafeError("path-mismatch", "directory final mode could not be verified");
+                }
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                fsSync.closeSync(fd);
+            },
+        };
+    }
+    catch (error) {
+        fsSync.closeSync(fd);
+        throw error;
+    }
+}

package/dist/effective-uid.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveEffectiveUid(): number;
+//# sourceMappingURL=effective-uid.d.ts.map

package/dist/effective-uid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-uid.d.ts","sourceRoot":"","sources":["../src/effective-uid.ts"],"names":[],"mappings":"AAUA,wBAAgB,mBAAmB,IAAI,MAAM,CAe5C"}

package/dist/effective-uid.js

@@ -0,0 +1,25 @@
+function isValidUid(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function unavailable(cause) {
+    return new Error("Effective user identity is unavailable.", {
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+export function resolveEffectiveUid() {
+    const provider = process.geteuid;
+    if (typeof provider !== "function") {
+        throw unavailable();
+    }
+    let uid;
+    try {
+        uid = provider.call(process);
+    }
+    catch (cause) {
+        throw unavailable(cause);
+    }
+    if (!isValidUid(uid)) {
+        throw unavailable();
+    }
+    return uid;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"file-handle-transfer.d.ts","sourceRoot":"","sources":["../src/file-handle-transfer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAWnD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC;AAEF,uFAAuF;AACvF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAGD,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,qBAAqB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,MAAM,CAAC,CAyBjB"}
+{"version":3,"file":"file-handle-transfer.d.ts","sourceRoot":"","sources":["../src/file-handle-transfer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAWnD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC;AAkDF,uFAAuF;AACvF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA0CjB;AAGD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,qBAAqB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/file-handle-transfer.js

@@ -3,61 +3,132 @@ import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult, composeMutationAssertions, rethrowMutationAuthorityError, } from "./mutation-authority.js";
 import { writeAllToFile } from "./write-file-handle.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
+const NO_CALLBACK_ARGUMENTS = Object.freeze([]);
+function defineReceiverValue(receiver, key, value) {
+    Object.defineProperty(receiver, key, {
+        value, enumerable: true, writable: true, configurable: true,
+    });
+}
+function copyTransferReceiver(options, maxBytes, sizeHint, signal, onChunk, assertBeforeMutation) {
+    const receiver = {};
+    const spreadSource = Object(options);
+    // Preserve the former late object-spread boundary, including proxy traps and
+    // unrelated getter failures. Authority-bearing values stay on their early
+    // snapshots, while descriptors still run in original own-key order.
+    for (const key of Reflect.ownKeys(spreadSource)) {
+        if (!Object.getOwnPropertyDescriptor(spreadSource, key)?.enumerable)
+            continue;
+        let value;
+        switch (key) {
+            case "maxBytes":
+                value = maxBytes;
+                break;
+            case "signal":
+                value = signal;
+                break;
+            case "onChunk":
+                value = onChunk;
+                break;
+            case "assertBeforeMutation":
+                value = assertBeforeMutation;
+                break;
+            default: value = Reflect.get(spreadSource, key);
+        }
+        // Create a data property so an enumerable __proto__ key cannot alter the
+        // ordinary receiver prototype, matching object spread.
+        defineReceiverValue(receiver, key, value);
+    }
+    // Match the explicit fields that followed the former spread. Updating an
+    // existing key retains its original position; absent keys append in order.
+    defineReceiverValue(receiver, "maxBytes", maxBytes);
+    defineReceiverValue(receiver, "sizeHint", sizeHint);
+    defineReceiverValue(receiver, "targetPosition", 0);
+    defineReceiverValue(receiver, "assertBeforeMutation", assertBeforeMutation);
+    return receiver;
+}
 /** Copies caller-owned regular files from offset zero without moving either cursor. */
 export async function copyFileHandle(source, target, options = {}) {
-    options.signal?.throwIfAborted();
+    // Snapshot caller-owned options before the first await. This preserves
+    // inherited/non-enumerable callbacks and prevents accessor mutation from
+    // replacing cancellation or mutation authority mid-transfer.
+    const signal = options.signal;
+    signal?.throwIfAborted();
     const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const onChunk = options.onChunk;
+    const assertBeforeMutation = composeMutationAssertions(undefined, options.assertBeforeMutation);
     const sourceStat = await inspectFileIdentity(() => {
-        options.signal?.throwIfAborted();
+        signal?.throwIfAborted();
         return source.stat({ bigint: true });
     });
-    options.signal?.throwIfAborted();
+    signal?.throwIfAborted();
     if (!sourceStat.isFile())
         throw new FsSafeError("not-file", "copy source handle must be a regular file");
     if (maxBytes !== undefined && Number.isFinite(maxBytes) && sourceStat.size > BigInt(maxBytes)) {
         throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`);
     }
     const targetStat = await inspectFileIdentity(() => {
-        options.signal?.throwIfAborted();
+        signal?.throwIfAborted();
         return target.stat({ bigint: true });
     });
-    options.signal?.throwIfAborted();
+    signal?.throwIfAborted();
     if (!targetStat.isFile())
         throw new FsSafeError("not-file", "copy target handle must be a regular file");
     if (sourceStat.dev === targetStat.dev && sourceStat.ino === targetStat.ino) {
         throw new FsSafeError("path-alias", "copy source and target handles refer to the same file");
     }
-    return await transferFileHandle(source, target, {
-        ...options,
-        maxBytes,
-        sizeHint: Number(sourceStat.size),
-        targetPosition: 0,
-        assertBeforeMutation: composeMutationAssertions(undefined, options.assertBeforeMutation),
-    }).catch(rethrowMutationAuthorityError);
+    const sizeHint = Number(sourceStat.size);
+    const callbackThis = copyTransferReceiver(options, maxBytes, sizeHint, signal, onChunk, assertBeforeMutation);
+    const beforeWrite = () => {
+        signal?.throwIfAborted();
+        assertBeforeMutation?.();
+    };
+    return await transferFileHandleCore(source, target, sizeHint, maxBytes, 0, signal, onChunk, beforeWrite, callbackThis).catch(rethrowMutationAuthorityError);
 }
 // Root.copyIn supplies already-admitted identities and retains its owned target cursor.
-export async function transferFileHandle(source, target, options) {
-    const maxBytes = options.maxBytes ?? Infinity;
-    const buffer = Buffer.allocUnsafe(Math.min(512 * 1024, Math.max(64 * 1024, options.sizeHint), maxBytes + 1));
+export function transferFileHandle(source, target, options) {
+    try {
+        const maxBytes = options.maxBytes;
+        const sizeHint = options.sizeHint;
+        const targetPosition = options.targetPosition;
+        const signal = options.signal;
+        const onChunk = options.onChunk;
+        const assertBeforeMutation = options.assertBeforeMutation;
+        const beforeWrite = signal === undefined && assertBeforeMutation === undefined
+            ? undefined
+            : () => {
+                signal?.throwIfAborted();
+                if (assertBeforeMutation) {
+                    Reflect.apply(assertBeforeMutation, options, NO_CALLBACK_ARGUMENTS);
+                }
+            };
+        return transferFileHandleCore(source, target, sizeHint, maxBytes, targetPosition, signal, onChunk, beforeWrite, options);
+    }
+    catch (error) {
+        // Keep the former async-function contract for synchronous option getters.
+        return Promise.reject(error);
+    }
+}
+async function transferFileHandleCore(source, target, sizeHint, maxBytes, targetPosition, signal, onChunk, beforeWrite, callbackThis) {
+    const limit = maxBytes ?? Infinity;
+    const buffer = Buffer.allocUnsafe(Math.min(512 * 1024, Math.max(64 * 1024, sizeHint), limit + 1));
     let position = 0;
     while (true) {
-        options.signal?.throwIfAborted();
-        const { bytesRead } = await source.read(buffer, 0, Math.min(buffer.length, maxBytes - position + 1), position);
-        options.signal?.throwIfAborted();
-        if (bytesRead > maxBytes - position) {
-            throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`);
+        signal?.throwIfAborted();
+        const { bytesRead } = await source.read(buffer, 0, Math.min(buffer.length, limit - position + 1), position);
+        signal?.throwIfAborted();
+        if (bytesRead > limit - position) {
+            throw new FsSafeError("too-large", `file exceeds limit of ${limit} bytes`);
         }
         if (bytesRead === 0)
             return position;
         const chunk = buffer.subarray(0, bytesRead);
-        if (options.onChunk)
-            assertSynchronousCallbackResult(options.onChunk(chunk), "onChunk");
+        if (onChunk) {
+            const returned = Function.prototype.call.call(onChunk, callbackThis, chunk);
+            assertSynchronousCallbackResult(returned, "onChunk");
+        }
         await writeAllToFile(target, chunk, {
-            position: options.targetPosition === undefined ? undefined : options.targetPosition + position,
-            assertBeforeMutation: () => {
-                options.signal?.throwIfAborted();
-                options.assertBeforeMutation?.();
-            },
+            position: targetPosition === undefined ? undefined : targetPosition + position,
+            assertBeforeMutation: beforeWrite,
         });
         position += bytesRead;
     }

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

@@ -1 +1 @@
-{"version":3,"file":"file-hash.d.ts","sourceRoot":"","sources":["../src/file-hash.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAInE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;AAClD,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,CAAC;AAElD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,aAAa,GAAG,SAA8B,EACtD,EAAE,QAAmB,EAAE,MAAM,EAAE,GAAE,iBAAsB,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAoD3B;AAyDD,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAoDD,8FAA8F;AAC9F,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAMlB"}
+{"version":3,"file":"file-hash.d.ts","sourceRoot":"","sources":["../src/file-hash.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAKnE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;AAClD,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,CAAC;AAElD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,aAAa,GAAG,SAA8B,EACtD,EAAE,QAAmB,EAAE,MAAM,EAAE,GAAE,iBAAsB,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAwD3B;AA0DD,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAwDD,8FAA8F;AAC9F,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAMlB"}