@openclaw/fs-safe 0.15.0 → 0.17.0

package/dist/root-impl.js

@@ -56,6 +56,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertCopySourceCurrent, resolveFileCopyCloneMode } from "./copy-file-input.js";
+import { assertPrivateFileCreationAvailable, resolveCreationPermissions } from "./creation-permissions.js";
 import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
@@ -71,18 +72,19 @@ import { validatePinnedOperationPayload } from "./pinned-operation.js";
 import { PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { assertNoNulPathInput, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError, } from "./path.js";
 import { readOpenedFileSafely } from "./read-opened-file.js";
-import { cleanupPinnedFilePath, removePathIfIdentityUnchanged } from "./replace-file-temp-owner.js";
+import { cleanupPinnedFilePath } from "./file-cleanup.js";
+import { removePathIfIdentityUnchanged } from "./replace-file-temp-owner.js";
 import { realpathSync } from "./realpath.js";
 import { mkdirPathFallback, prepareRootWriteTarget, tryMkdirAtExactParent } from "./root-directory-creation.js";
 import { isNonRegularWriteOpenError, resolveNonblockingWriteFlag } from "./write-open-flags.js";
-import { resolveRootPath, resolveRootPathForRemoval } from "./root-path.js";
+import { resolveRootPath, resolveRootPathSync, resolveRootPathForRemoval } from "./root-path.js";
 import { RemovalPathReceipts } from "./root-remove-receipt.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { listDirectoryPath, openRootDirectoryListing } from "./root-directory-list.js";
 import { statResolvedPathInRoot } from "./root-path-stat.js";
 import { entriesInRoot } from "./root-entries.js";
 import { assertMoveMutationAllowed } from "./root-move-preflight.js";
-import { assertRootIdentityCurrent, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
+import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
 import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
@@ -97,7 +99,7 @@ import { finishRootFallbackWrite } from "./root-write-publication.js";
 import { withRootFallbackCompatibilityLock } from "./root-write-compatibility.js";
 import { assertRootFallbackWritePath } from "./root-write-lock-binding.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
-import { movePathNoReplaceNative } from "./root-move-noreplace.js";
+import { admitMoveSourceStat, movePathNoReplaceNative } from "./root-move-noreplace.js";
 import { admitRootReadHandle, inspectOpenedPathIdentitySync } from "./root-read-admission.js";
 import { createCopyPublicationObserver, onCopyPublication, onCopySourceAdmission } from "./copy-publication.js";
 import { writeAllToFile } from "./write-file-handle.js";
@@ -315,13 +317,15 @@ export class RootHandle {
     }
     async create(relativePath, data, options = {}) {
         assertValidRootDestinationPath(relativePath);
+        const durable = options.durable ?? this.defaults.durable ?? true;
         await writeFileInRoot(this.context, {
             relativePath,
             data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...this.mutationOptions(createInputOptions(data, options, this.defaults.maxBytes)),
-            durable: options.durable ?? this.defaults.durable ?? true,
+            durable: durable !== false,
+            strictFileSync: durable === "file",
             overwrite: false,
         }).catch(rethrowMutationAuthorityError).catch(rethrowCreateInputError);
     }
@@ -377,7 +381,9 @@ export class RootHandle {
         assertValidRootRelativePath(fromRelative);
         assertValidRootDestinationPath(toRelative);
         validatePinnedOperationPayload({ from: fromRelative, to: toRelative });
-        const { denyMutations, assertBeforeMutation, mutationSymlinks } = this.mutationOptions(options);
+        const mutationOptions = this.mutationOptions(options);
+        const { assertBeforeMutation } = mutationOptions;
+        const { denyMutations, mutationSymlinks } = snapshotPinnedMutationPolicy(mutationOptions.denyMutations, mutationOptions.mutationSymlinks) ?? {};
         const overwrite = options.overwrite ?? false;
         await assertMoveMutationAllowed(this.context, {
             fromRelative,
@@ -717,8 +723,9 @@ async function appendFileInRoot(root, params) {
             if (params.prependNewlineIfNeeded === true &&
                 !target.createdForWrite &&
                 target.stat.size > 0 &&
+                params.data.length > 0 &&
                 ((typeof params.data === "string" && !params.data.startsWith("\n")) ||
-                    (Buffer.isBuffer(params.data) && params.data.length > 0 && params.data[0] !== 0x0a))) {
+                    (Buffer.isBuffer(params.data) && params.data[0] !== 0x0a))) {
                 const newline = Buffer.from("\n", typeof params.data === "string" ? params.encoding : "utf8");
                 const tail = Buffer.alloc(newline.length);
                 const { bytesRead } = await target.handle.read(tail, 0, tail.length, Math.max(0, target.stat.size - tail.length));
@@ -778,6 +785,7 @@ async function removePathInRoot(root, params) {
     }
 }
 async function mkdirPathInRoot(root, params) {
+    const privateMode = resolveCreationPermissions(params, true).private;
     validatePinnedOperationPayload({ relativePath: params.relativePath });
     const policy = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
@@ -810,19 +818,23 @@ async function mkdirPathInRoot(root, params) {
         await getFsSafeTestHooks()?.beforePinnedWriteParentAdmission?.(resolved.resolved);
     }
     try {
-        if (prepared?.mutationAdmission && params.assertBeforeMutation === undefined &&
+        if (!privateMode && prepared?.mutationAdmission && params.assertBeforeMutation === undefined &&
             await tryMkdirAtExactParent(root, resolved.resolved, prepared.mutationAdmission))
             return;
-        await mkdirPathFallback(root, resolved, params.assertBeforeMutation, policy?.mutationSymlinks !== undefined, prepared?.mutationAdmission);
+        await mkdirPathFallback(root, resolved, params.assertBeforeMutation, policy?.mutationSymlinks !== undefined, prepared?.mutationAdmission, privateMode);
     }
     catch (error) {
         throw normalizePinnedPathError(error);
     }
 }
 async function writeFileInRoot(root, params) {
+    if (params.private !== undefined) {
+        const permissions = resolveCreationPermissions(params, false);
+        params = { ...params, private: permissions.private, mode: permissions.mode };
+    }
     const input = rootWriteInput(params);
     await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
-        if (input.kind === "buffer" && process.platform === "win32" &&
+        if (!params.private && input.kind === "buffer" && !input.stageBeforePublish && process.platform === "win32" &&
             (params.renameIdentity === "verify-content-with-lock" || !getNativeBinding())) {
             await writeFileFallback(root, { ...params, data: input.data });
             return;
@@ -836,15 +848,25 @@ async function writeFileInRoot(root, params) {
 async function commitPinnedWriteInRoot(root, pinned, params, input) {
     let verifyingPublication = false;
     try {
+        if (params.private)
+            assertPrivateFileCreationAvailable();
+        if (params.private && params.mkdir !== false) {
+            const target = await prepareRootWriteTarget(root, pinned.targetPath, params.assertBeforeMutation, pinned.mutationAdmission, true);
+            if (target !== pinned.targetPath) {
+                throw new FsSafeError("path-mismatch", "private creation parent changed during admission");
+            }
+        }
         await runPinnedWriteWithRenamePolicy({
             rootPath: pinned.rootReal,
             relativeParentPath: pinned.relativeParentPath,
             basename: pinned.basename,
             targetPath: pinned.targetPath,
             renameIdentity: params.renameIdentity,
-            mkdir: params.mkdir !== false,
+            mkdir: !params.private && params.mkdir !== false,
+            private: params.private,
             mode: params.mode ?? pinned.mode,
             sync: params.durable !== false,
+            strictFileSync: params.strictFileSync,
             overwrite: params.overwrite,
             rejectFinalSymlink: params.mutationSymlinks !== undefined,
             input,
@@ -1064,6 +1086,8 @@ async function listPathFallback(root, relativePath, withFileTypes) {
     return await listDirectoryPath(root, resolved.resolved, withFileTypes, resolved.receipt);
 }
 async function movePathFallback(root, params) {
+    const originalRoutes = params.overwrite && params.assertBeforeMutation
+        ? await Promise.all([params.fromRelative, params.toRelative].map(expandRelativePathWithHome)) : undefined;
     const source = await resolvePathInRoot(root, params.fromRelative, {
         aliasErrorCode: "path-alias",
         allowFinalSymlink: true,
@@ -1099,9 +1123,14 @@ async function movePathFallback(root, params) {
                 targetStat?.isSymbolicLink() === true);
         },
     });
-    let sourceStat;
+    let sourceIdentity;
     try {
-        sourceStat = fsSync.lstatSync(source.resolved);
+        if (params.overwrite && params.assertBeforeMutation) {
+            sourceIdentity = inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(source.resolved, { bigint: true }), true));
+        }
+        else {
+            admitMoveSourceStat(fsSync.lstatSync(source.resolved), params.overwrite);
+        }
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
@@ -1109,19 +1138,10 @@ async function movePathFallback(root, params) {
         }
         throw error;
     }
-    if (sourceStat.isSymbolicLink()) {
-        throw new FsSafeError("symlink", "symlink not allowed");
-    }
-    if (sourceStat.isFile() && sourceStat.nlink > 1) {
-        throw hardlinkedPathNotAllowedError();
-    }
-    if (!params.overwrite && sourceStat.isDirectory()) {
-        throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
+    if (!pinnedTarget) {
+        throw new FsSafeError("path-mismatch", "destination admission was not completed");
     }
     if (!params.overwrite) {
-        if (!pinnedTarget) {
-            throw new FsSafeError("path-mismatch", "destination admission was not completed");
-        }
         await movePathNoReplaceNative(root, params, {
             sourcePath: source.resolved,
             sourceParentPath: path.dirname(pinnedSource.canonicalPath),
@@ -1130,8 +1150,9 @@ async function movePathFallback(root, params) {
         });
         return;
     }
-    const sourceParentGuard = await createAsyncDirectoryGuard(path.dirname(source.resolved));
-    const targetParentGuard = await createNearestExistingDirectoryGuard(target.rootReal, path.dirname(target.resolved));
+    const guardOptions = { bigint: sourceIdentity !== undefined };
+    const sourceParentGuard = await createAsyncDirectoryGuard(path.dirname(source.resolved), guardOptions);
+    const targetParentGuard = await createNearestExistingDirectoryGuard(target.rootReal, path.dirname(target.resolved), guardOptions);
     await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("move", target.resolved);
     await assertAsyncDirectoryGuard(sourceParentGuard);
     await assertAsyncDirectoryGuard(targetParentGuard);
@@ -1139,6 +1160,31 @@ async function movePathFallback(root, params) {
         assertFinalSymlinkRejected(source.resolved, params.mutationSymlinks !== undefined);
         assertFinalSymlinkRejected(target.resolved, params.mutationSymlinks !== undefined);
         params.assertBeforeMutation?.();
+        if (sourceIdentity) {
+            assertRootIdentityCurrentSync(root);
+            assertSyncDirectoryGuard(sourceParentGuard);
+            assertSyncDirectoryGuard(targetParentGuard);
+            for (const [route, selected, expected, policy] of [
+                [originalRoutes[0], source.resolved, pinnedSource.canonicalPath, PATH_ALIAS_POLICIES.strict],
+                [originalRoutes[1], target.resolved, pinnedTarget.canonicalPath, PATH_ALIAS_POLICIES.unlinkTarget],
+            ]) {
+                for (const absolutePath of new Set([path.isAbsolute(route) ? route : `${root.rootWithSep}${route}`, selected])) {
+                    try {
+                        const current = resolveRootPathSync({
+                            absolutePath, rootPath: root.rootReal, rootCanonicalPath: root.rootReal,
+                            rootIdentity: root.rootIdentity, boundaryLabel: "root", policy,
+                            ...mutationSymlinkResolution(params.mutationSymlinks),
+                        });
+                        if (current.canonicalPath !== expected)
+                            throw new FsSafeError("path-mismatch", "move route changed during authorization");
+                    }
+                    catch (error) {
+                        throw normalizePinnedPathError(error);
+                    }
+                }
+            }
+            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(source.resolved, { bigint: true }), true), sourceIdentity);
+        }
         await fs.rename(source.resolved, target.resolved);
     }
     catch (error) {
@@ -1303,6 +1349,7 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
     const parentGuard = pathSelection?.parentGuard ??
         await createAsyncDirectoryGuard(path.dirname(targetPath), { bigint: true });
     let created = false;
+    let completed = false;
     let createdIdentity;
     let writtenHandle;
     let verifyingPublication = false;
@@ -1346,6 +1393,7 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
         });
         if (params.durable !== false)
             await syncDirectoryBestEffort(path.dirname(targetPath));
+        completed = true;
     }
     catch (err) {
         if (verifyingPublication)
@@ -1363,6 +1411,9 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
                 pathname: targetPath, handle: writtenHandle, identity: createdIdentity, parentGuard,
             });
         }
-        await writtenHandle?.close().catch(() => undefined);
+        if (completed)
+            await writtenHandle?.close();
+        else
+            await writtenHandle?.close().catch(() => undefined);
     }
 }

package/dist/root-move-noreplace.d.ts

@@ -1,6 +1,8 @@
+import { type BigIntStats, type Stats } from "node:fs";
 import { type DenyMutationPolicy } from "./deny-mutations.js";
 import { type RootContext } from "./root-context.js";
 import { type MutationSymlinkPolicy } from "./root-symlink-policy.js";
+export declare function admitMoveSourceStat<T extends Stats | BigIntStats>(stat: T, overwrite?: boolean): T;
 export declare function movePathNoReplaceNative(root: RootContext, params: {
     assertBeforeMutation?: () => void;
     denyMutations?: DenyMutationPolicy;

package/dist/root-move-noreplace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-move-noreplace.d.ts","sourceRoot":"","sources":["../src/root-move-noreplace.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAQvF,OAAO,EAA4D,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAU/G,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAqDlG,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE;IACN,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CAC1C,EACD,KAAK,EAAE;IACL,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GACA,OAAO,CAAC,IAAI,CAAC,CA0If"}
+{"version":3,"file":"root-move-noreplace.d.ts","sourceRoot":"","sources":["../src/root-move-noreplace.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAI/D,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAQvF,OAAO,EAA4D,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAU/G,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAsDlG,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,KAAK,GAAG,WAAW,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,UAAQ,GAAG,CAAC,CAWhG;AAED,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE;IACN,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CAC1C,EACD,KAAK,EAAE;IACL,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GACA,OAAO,CAAC,IAAI,CAAC,CAsIf"}

package/dist/root-move-noreplace.js

@@ -12,6 +12,7 @@ import { admitPathInsideRoot } from "./root-boundary.js";
 import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, outsideWorkspaceError, } from "./root-errors.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 import { createSuppressedError } from "./suppressed-error.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 function nativeParentRelativePath(rootReal, parentPath) {
     const relative = path.relative(rootReal, parentPath);
@@ -57,6 +58,18 @@ function normalizeRenameNoReplaceError(error) {
     }
     return normalizeMoveError(error);
 }
+export function admitMoveSourceStat(stat, overwrite = false) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", "symlink not allowed");
+    }
+    if (stat.isFile() && stat.nlink > 1) {
+        throw hardlinkedPathNotAllowedError();
+    }
+    if (!overwrite && stat.isDirectory()) {
+        throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
+    }
+    return stat;
+}
 export async function movePathNoReplaceNative(root, params, paths) {
     try {
         fsSync.lstatSync(paths.targetPath);
@@ -104,21 +117,13 @@ export async function movePathNoReplaceNative(root, params, paths) {
         await assertRootIdentityCurrent(root);
         for (const admission of parentAdmissions)
             assertSyncDirectoryGuard(admission.guard);
+        // Capture an exact receipt only when admission must survive a callback.
         let sourceStat;
-        try {
-            sourceStat = fsSync.lstatSync(admittedSourcePath);
+        if (params.assertBeforeMutation) {
+            sourceStat = inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true })));
         }
-        catch (error) {
-            throw normalizeMoveError(error);
-        }
-        if (sourceStat.isSymbolicLink()) {
-            throw new FsSafeError("symlink", "symlink not allowed");
-        }
-        if (sourceStat.isFile() && sourceStat.nlink > 1) {
-            throw hardlinkedPathNotAllowedError();
-        }
-        if (sourceStat.isDirectory()) {
-            throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
+        else {
+            admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath));
         }
         assertFinalSymlinkRejected(admittedTargetPath, params.mutationSymlinks !== undefined);
         params.assertBeforeMutation?.();
@@ -143,6 +148,10 @@ export async function movePathNoReplaceNative(root, params, paths) {
             for (const admission of parentAdmissions)
                 assertSyncDirectoryGuard(admission.guard);
         }
+        // The callback can change a leaf without replacing its admitted parent.
+        if (sourceStat !== undefined) {
+            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true })), sourceStat);
+        }
         try {
             binding.renameNoReplace(sourceParent.fd, path.basename(paths.sourcePath), targetParent.fd, path.basename(paths.targetPath));
         }

package/dist/root-options.d.ts

@@ -50,12 +50,18 @@ export type RootWriteJsonOptions = RootWriteOptions & {
     space?: Parameters<typeof JSON.stringify>[2];
     trailingNewline?: boolean;
 };
-export type RootCreateOptions = Omit<RootWriteOptions, "overwrite">;
-export type RootCreateStreamOptions = Omit<RootCreateOptions, "encoding" | "renameIdentity"> & {
+export type RootCreateOptions = Omit<RootWriteOptions, "overwrite" | "durable"> & {
+    /** Publish complete content without replacing an existing entry, including without native support. */
+    atomic?: boolean;
+    private?: boolean;
+    /** "file" requires file synchronization; directory synchronization remains best effort. */
+    durable?: boolean | "file";
+};
+export type RootCreateStreamOptions = Omit<RootCreateOptions, "atomic" | "encoding" | "renameIdentity"> & {
     maxBytes?: number;
     signal?: AbortSignal;
 };
-export type RootCreateJsonOptions = Omit<RootWriteJsonOptions, "overwrite">;
+export type RootCreateJsonOptions = Omit<RootWriteJsonOptions, "overwrite" | "durable"> & Pick<RootCreateOptions, "atomic" | "durable" | "private">;
 export type RootAppendOptions = RootWriteOptions & {
     prependNewlineIfNeeded?: boolean;
 };
@@ -70,7 +76,9 @@ export type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "den
     maxDepth?: number;
     signal?: AbortSignal;
 };
-export type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">;
+export type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+    private?: boolean;
+};
 export type RootReadParams = Omit<RootReadOptions, "nonBlockingRead">;
 export declare function readDefaults(defaults: RootDefaults): RootReadParams;
 export declare function mergeReadOptions(defaults: RootDefaults, options: RootReadOptions): RootReadParams;

package/dist/root-options.d.ts.map

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

package/dist/root-path-stat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-path-stat.d.ts","sourceRoot":"","sources":["../src/root-path-stat.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAIjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAwB3C,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,QAAQ,CAAC,CA8EnB"}
+{"version":3,"file":"root-path-stat.d.ts","sourceRoot":"","sources":["../src/root-path-stat.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAIjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA2D3C,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,QAAQ,CAAC,CAUnB"}

package/dist/root-path-stat.js

@@ -1,14 +1,37 @@
 import fsSync from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { recordFileObservationFailure } from "./file-observation.js";
+import { fileObservation, recordFileObservationFailure } from "./file-observation.js";
 import { hasNodeErrorCode, isNotFoundPathError } from "./path.js";
 import { assertRootDirectoryObservationGuard, assertRootPathObservationReceiptCurrent, createRootDirectoryObservationGuard, pathStatFromStats, } from "./root-directory-list.js";
 import { fileNotFoundError } from "./root-errors.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertStatObservationSync } from "./stat-observation.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-async function missingObservedFileError(cause, pathname, before, assertParents) {
+function singleLinkFileIdentity(stat) {
+    if (!stat?.isFile() || stat.isSymbolicLink() || (stat.nlink !== 1 && stat.nlink !== 1n))
+        return;
+    const exact = (value) => typeof value === "bigint" ? value : Number.isSafeInteger(value) ? BigInt(value) : undefined;
+    const dev = exact(stat.dev), ino = exact(stat.ino);
+    if (dev === undefined || ino === undefined || dev < 0n || ino < 0n ||
+        (process.platform === "win32" && (dev === 0n || ino === 0n)))
+        return;
+    return { dev, ino };
+}
+async function captureChangedObservedFile(error, pathname, before, observed, assertParents, proof) {
+    try {
+        const previous = singleLinkFileIdentity(before), current = singleLinkFileIdentity(observed);
+        if (!previous || !current || (previous.dev === current.dev && previous.ino === current.ino))
+            return;
+        await assertParents();
+        // A changed metadata probe grants only a fresh acquisition attempt, never ownership.
+        proof.failure = { error, kind: `stat-leaf-changed:${pathname}` };
+    }
+    catch {
+        // Ambiguous file or ancestry observations retain the original public error.
+    }
+}
+async function missingObservedFileError(cause, pathname, before, assertParents, proof) {
     const failure = new FsSafeError("path-mismatch", "file changed during operation", {
         cause: cause instanceof Error ? cause : undefined,
     });
@@ -17,7 +40,7 @@ async function missingObservedFileError(cause, pathname, before, assertParents)
         try {
             await assertParents();
             // Metadata loss permits discarding a probe, never reading or owning a file.
-            recordFileObservationFailure(failure, `stat-leaf-missing:${pathname}`);
+            proof.failure = { error: failure, kind: `stat-leaf-missing:${pathname}` };
         }
         catch {
             // Keep the public mismatch and withhold provenance when ancestry changed.
@@ -26,6 +49,19 @@ async function missingObservedFileError(cause, pathname, before, assertParents)
     return failure;
 }
 export async function statResolvedPathInRoot(root, resolvedPath, receipt) {
+    const proof = {};
+    try {
+        // Nested observations in a hook cannot grant this invocation discard authority.
+        return await fileObservation().run(() => statObservedPathInRoot(root, resolvedPath, proof, receipt));
+    }
+    catch (error) {
+        const failure = proof.failure;
+        if (failure && failure.error === error)
+            recordFileObservationFailure(error, failure.kind);
+        throw error;
+    }
+}
+async function statObservedPathInRoot(root, resolvedPath, proof, receipt) {
     let admittedTarget = false;
     try {
         if (receipt) {
@@ -37,13 +73,21 @@ export async function statResolvedPathInRoot(root, resolvedPath, receipt) {
             if (beforeObservation)
                 await beforeObservation(resolvedPath);
             let observed;
+            let sample, samples = 0;
+            const comparison = fileObservation();
             try {
-                observed = assertStatObservationSync(bigint => bigint ? fsSync.lstatSync(resolvedPath, { bigint: true }) : fsSync.lstatSync(resolvedPath), receipt.target.identity);
+                observed = comparison.run(() => assertStatObservationSync(bigint => {
+                    sample = bigint ? fsSync.lstatSync(resolvedPath, { bigint: true }) : fsSync.lstatSync(resolvedPath);
+                    samples += 1;
+                    return sample;
+                }, receipt.target.identity));
             }
             catch (error) {
                 if (isNotFoundPathError(error)) {
-                    throw await missingObservedFileError(error, resolvedPath, "stat" in receipt.target ? receipt.target.stat : undefined, () => assertRootPathObservationReceiptCurrent(root, receipt));
+                    throw await missingObservedFileError(error, resolvedPath, "stat" in receipt.target ? receipt.target.stat : undefined, () => assertRootPathObservationReceiptCurrent(root, receipt), proof);
                 }
+                if (comparison.has(error, "identity"))
+                    await captureChangedObservedFile(error, resolvedPath, "stat" in receipt.target ? receipt.target.stat : undefined, samples === 1 ? sample : undefined, () => assertRootPathObservationReceiptCurrent(root, receipt), proof);
                 throw error;
             }
             if (observed.isSymbolicLink()) {
@@ -77,13 +121,21 @@ export async function statResolvedPathInRoot(root, resolvedPath, receipt) {
         if (beforeObservation)
             await beforeObservation(resolvedPath);
         let observed;
+        let sample, samples = 0;
+        const comparison = fileObservation();
         try {
-            observed = inspectFileIdentitySync(() => fsSync.lstatSync(resolvedPath, { bigint: true }), expected);
+            observed = comparison.run(() => inspectFileIdentitySync(() => {
+                sample = fsSync.lstatSync(resolvedPath, { bigint: true });
+                samples += 1;
+                return sample;
+            }, expected));
         }
         catch (error) {
             if (isNotFoundPathError(error)) {
-                throw await missingObservedFileError(error, resolvedPath, expected, () => assertRootDirectoryObservationGuard(root, parentGuard));
+                throw await missingObservedFileError(error, resolvedPath, expected, () => assertRootDirectoryObservationGuard(root, parentGuard), proof);
             }
+            if (comparison.has(error, "identity"))
+                await captureChangedObservedFile(error, resolvedPath, expected, samples === 1 ? sample : undefined, () => assertRootDirectoryObservationGuard(root, parentGuard), proof);
             throw error;
         }
         if (observed.isSymbolicLink()) {

package/dist/root-read-admission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-read-admission.d.ts","sourceRoot":"","sources":["../src/root-read-admission.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAmB9D,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,GAAG,SAAS,GAClC,WAAW,CAQb;AA6CD,KAAK,mBAAmB,GAAG;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACzB,CAAC;AAEF,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,mBAAmB,EAAE,MAAM,EAAE;IAC/E,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;IACV,QAAQ,EAAE,WAAW,CAAC;IACtB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClF,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;CACzE,GAAG,OAAO,CAAC,CAAC,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA8BpC"}
+{"version":3,"file":"root-read-admission.d.ts","sourceRoot":"","sources":["../src/root-read-admission.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAmB9D,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,GAAG,SAAS,GAClC,WAAW,CAQb;AAgDD,KAAK,mBAAmB,GAAG;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACzB,CAAC;AAEF,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,mBAAmB,EAAE,MAAM,EAAE;IAC/E,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;IACV,QAAQ,EAAE,WAAW,CAAC;IACtB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClF,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;CACzE,GAAG,OAAO,CAAC,CAAC,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA+BpC"}

package/dist/root-read-admission.js

@@ -35,7 +35,9 @@ function assertRootReadAdmissionCurrent(params) {
     assertRootIdentityCurrentSync(params.root);
     const admittedPath = (() => {
         try {
-            inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(params.filePath, params.symlinks), params.identity);
+            const current = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(params.filePath, params.symlinks), params.identity);
+            if (params.hardlinks !== "allow" && current.nlink > 1n)
+                throw hardlinkedPathNotAllowedError();
             const canonicalPath = resolveFinalOpenedRealPath(params.filePath);
             assertNoWindowsPathAlias(canonicalPath, "filesystem", "resolved file path uses a Windows filesystem namespace alias");
             const admittedRealPath = admitPathInsideRoot({
@@ -48,7 +50,9 @@ function assertRootReadAdmissionCurrent(params) {
             }
             // This is a fresh no-follow observation even when canonicalPath and
             // filePath have the same spelling; realpath may have raced a replacement.
-            inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(canonicalPath, undefined), params.identity);
+            const canonical = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(canonicalPath, undefined), params.identity);
+            if (params.hardlinks !== "allow" && canonical.nlink > 1n)
+                throw hardlinkedPathNotAllowedError();
             return admittedRealPath.path;
         }
         catch (error) {
@@ -75,6 +79,7 @@ export async function admitRootReadHandle(params) {
                 filePath: params.filePath,
                 handle: params.opened.handle,
                 identity: params.identity,
+                hardlinks: params.hardlinks,
                 symlinks: params.symlinks,
                 afterPathIdentityCheck: params.afterPathIdentityCheck,
             });

package/dist/root-remove.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-remove.d.ts","sourceRoot":"","sources":["../src/root-remove.ts"],"names":[],"mappings":"AAeA,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAM3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AASpE,eAAO,MAAM,uBAAuB,EAAE,OAAO,MAA4C,CAAC;AAK1F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAgBtE;AAyOD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,iBAAiB,EAC1B,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA6Lf"}
+{"version":3,"file":"root-remove.d.ts","sourceRoot":"","sources":["../src/root-remove.ts"],"names":[],"mappings":"AAeA,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAM3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AASpE,eAAO,MAAM,uBAAuB,EAAE,OAAO,MAA4C,CAAC;AAK1F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAgBtE;AAiPD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,iBAAiB,EAC1B,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAkMf"}

package/dist/root-remove.js

@@ -220,13 +220,21 @@ async function removeOne(root, targetPath, options, receipts) {
         throw normalizeRemoveGuardError(error);
     }
     try {
-        const isDirectory = fsSync.lstatSync(targetPath).isDirectory();
+        const identity = options.assertBeforeMutation
+            ? inspectFileIdentitySync(() => fsSync.lstatSync(targetPath, { bigint: true })) : undefined;
+        const isDirectory = (identity ?? fsSync.lstatSync(targetPath)).isDirectory();
         if (!isDirectory && options[nonrecursiveRemovalKind] === "directory") {
             throw new FsSafeError("path-mismatch", "store entry is no longer a directory");
         }
         assertFinalSymlinkRejected(targetPath, options.mutationSymlinks !== undefined);
         assertNotAborted(options.signal);
         options.assertBeforeMutation?.();
+        if (identity) {
+            assertNotAborted(options.signal);
+            admission.assertCurrent();
+            inspectFileIdentitySync(() => fsSync.lstatSync(targetPath, { bigint: true }), identity);
+            assertFinalSymlinkRejected(targetPath, options.mutationSymlinks !== undefined);
+        }
         await (isDirectory ? fs.rmdir(targetPath) : fs.unlink(targetPath));
     }
     catch (error) {
@@ -436,6 +444,12 @@ export async function removePathInRootFallback(root, targetPath, options, receip
         assertFinalSymlinkRejected(target, options.mutationSymlinks !== undefined, details(target, "remove"));
         assertNotAborted(options.signal);
         options.assertBeforeMutation?.();
+        if (options.assertBeforeMutation) {
+            assertNotAborted(options.signal);
+            if (!inspect(target, initial))
+                return;
+            assertFinalSymlinkRejected(target, options.mutationSymlinks !== undefined, details(target, "remove"));
+        }
         try {
             await (initial.isDirectory() ? fs.rmdir(target) : fs.unlink(target));
         }

package/dist/root-write-publication.js

@@ -4,7 +4,7 @@ import { readFileHandleBounded } from "./bounded-read.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
-import { cleanupPinnedFilePath } from "./replace-file-temp-owner.js";
+import { cleanupPinnedFilePath } from "./file-cleanup.js";
 import { verifyAtomicWriteResult } from "./root-write-verification.js";
 // Compatibility callers hold the lock throughout this operation. The caller
 // owns the original write handle; this helper owns a content-verified reopen.

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

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAM/C,OAAO,EAAkF,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAShJ,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAQjC,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CA2CR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;AA8JD,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AA+BF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,SAAS,CAAC,GAC7C,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC5C,WAAW,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAgCD;AAwDD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBzF"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAM/C,OAAO,EAAkF,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAShJ,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAQjC,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CA2CR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;AA8JD,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AA+BF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,SAAS,CAAC,GAC7C,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC5C,WAAW,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAgCD;AAyDD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBzF"}

package/dist/secret-file.js

@@ -291,6 +291,7 @@ async function materializeSecretFileAtomic(params, createOnly) {
         basename: fileName,
         mkdir: false,
         mode,
+        verifyPosixMode: true,
         sync: params.durable !== false,
         overwrite: !createOnly,
         input: { kind: "buffer", data: typeof params.content === "string" ? params.content : Buffer.from(params.content) },

package/dist/secure-file-windows.d.ts

@@ -6,5 +6,11 @@ export declare function inspectSecureWindowsDescriptor(params: {
     identity: ExactIdentity;
     stat: Stats;
 }): PermissionCheck;
+/** Both mechanisms inspect the same borrowed handle; the caller owns its lifetime. */
+export declare function inspectSecureWindowsFile(params: {
+    fd: number;
+    identity: ExactIdentity;
+    stat: Stats;
+}): Promise<PermissionCheck>;
 export {};
 //# sourceMappingURL=secure-file-windows.d.ts.map