@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/root-write-mode.js

@@ -1,26 +1,33 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
-import { isNotFoundPathError, isPathInside } from "./path.js";
+import { isNotFoundPathError } from "./path.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { realpathSync } from "./realpath.js";
 import { hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
 // The caller has already resolved and guarded this write target.
 export async function inheritWriteTargetMode(params) {
     try {
-        const existing = await inspectFileIdentity(() => fsSync.lstatSync(params.targetPath, { bigint: true }));
+        const admittedTarget = admitPathInsideRoot({
+            rootPath: params.rootWithSep,
+            candidatePath: params.targetPath,
+            rootIdentity: params.rootIdentity,
+        });
+        if (!admittedTarget)
+            throw outsideWorkspaceError();
+        const targetPath = admittedTarget.path;
+        const existing = await inspectFileIdentity(() => fsSync.lstatSync(targetPath, { bigint: true }));
         if (existing.isSymbolicLink())
             throw new FsSafeError("path-alias", "path alias escape blocked");
         if (!existing.isFile())
             throw new FsSafeError("not-file", "not a file");
         if (existing.nlink > 1n)
             throw hardlinkedPathNotAllowedError();
-        if (!isPathInside(params.rootWithSep, params.targetPath))
-            throw outsideWorkspaceError();
         // Preserve read-open admission of the pre-existing destination. access(2)
         // is not equivalent: it ignores ACLs on Windows and capabilities on Linux.
-        const handle = await fs.open(params.targetPath, resolveReadOpenFlags());
+        const handle = await fs.open(targetPath, resolveReadOpenFlags());
         try {
             // Bind admission to the inode whose metadata is inherited.
             await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), existing);
@@ -31,9 +38,15 @@ export async function inheritWriteTargetMode(params) {
         try {
             // A parent can change after guarded resolution. Do not inherit metadata
             // from an outside inode, even if the parent is restored before publication.
-            const realPath = realpathSync.native(params.targetPath);
-            if (!isPathInside(params.rootWithSep, realPath))
+            const observedRealPath = realpathSync.native(targetPath);
+            const admittedRealPath = admitPathInsideRoot({
+                rootPath: params.rootWithSep,
+                candidatePath: observedRealPath,
+                rootIdentity: params.rootIdentity,
+            });
+            if (!admittedRealPath)
                 throw outsideWorkspaceError();
+            const realPath = admittedRealPath.path;
             await inspectFileIdentity(async () => {
                 const current = fsSync.statSync(realPath, { bigint: true });
                 if (!current.isFile())

package/dist/root-write-publication.d.ts

@@ -0,0 +1,24 @@
+import { type BigIntStats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { RootContext } from "./root-context.js";
+import type { RootWriteOptions } from "./root-options.js";
+export declare function finishRootFallbackWrite(params: {
+    root: RootContext;
+    targetPath: string;
+    handle: FileHandle;
+    identity: BigIntStats;
+    parentGuard: AnyAsyncDirectoryGuard;
+    mode: number;
+    options: RootWriteOptions & {
+        data: string | Buffer;
+    };
+    openForCompatibility: () => Promise<{
+        opened: {
+            handle: FileHandle;
+        };
+        identity: BigIntStats;
+    }>;
+    onVerificationFailure: (error: unknown) => void;
+}): Promise<void>;
+//# sourceMappingURL=root-write-publication.d.ts.map

package/dist/root-write-publication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-write-publication.d.ts","sourceRoot":"","sources":["../src/root-write-publication.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAKnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAK1D,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,WAAW,EAAE,sBAAsB,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACtD,oBAAoB,EAAE,MAAM,OAAO,CAAC;QAAE,MAAM,EAAE;YAAE,MAAM,EAAE,UAAU,CAAA;SAAE,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IAC/F,qBAAqB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD,GAAG,OAAO,CAAC,IAAI,CAAC,CAoEhB"}

package/dist/root-write-publication.js

@@ -0,0 +1,85 @@
+import fsSync, {} from "node:fs";
+import path from "node:path";
+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 { 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.
+export async function finishRootFallbackWrite(params) {
+    let handle = params.handle;
+    let identity = params.identity;
+    let accepted;
+    const compatibility = params.options.renameIdentity === "verify-content-with-lock";
+    const verify = async () => {
+        try {
+            await verifyAtomicWriteResult({
+                root: params.root, targetPath: params.targetPath, fd: handle.fd,
+                expectedIdentity: identity, parentGuard: params.parentGuard,
+            });
+        }
+        catch (error) {
+            params.onVerificationFailure(error);
+            throw error;
+        }
+    };
+    try {
+        if (compatibility) {
+            const current = fsSync.lstatSync(params.targetPath, { bigint: true });
+            if (current.isSymbolicLink() || !current.isFile()) {
+                throw new FsSafeError("path-mismatch", "fallback target changed during write");
+            }
+            if (process.platform === "win32" && (current.dev === 0n || current.ino === 0n)) {
+                // Opaque pathname stats are not evidence of rename identity drift. The
+                // strict verifier can reopen against the retained descriptor's exact
+                // identity without reading bytes; a different object must still fail.
+                await verify();
+            }
+            else if (!sameFileIdentityForCleanup(current, identity)) {
+                const opened = await params.openForCompatibility();
+                accepted = handle = opened.opened.handle;
+                identity = opened.identity;
+                // Admit the destination under the retained Root and parent before any
+                // read, chmod, or sync; the original temp no longer proves its identity.
+                await verify();
+                const data = params.options.data;
+                const expectedBytes = typeof data === "string"
+                    ? Buffer.byteLength(data, params.options.encoding ?? "utf8") : data.byteLength;
+                const content = await readFileHandleBounded(handle, expectedBytes).catch((error) => {
+                    if (error instanceof FsSafeError && error.code === "too-large") {
+                        throw new FsSafeError("path-mismatch", "fallback target changed during write", { cause: error });
+                    }
+                    throw error;
+                });
+                if (sha256Hex(content) !== sha256Hex(data, params.options.encoding)) {
+                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
+                }
+                await verify();
+            }
+        }
+        // Final mode belongs to the accepted object, including on rename-unstable
+        // filesystems; never chmod the old temp and assume its mode was transferred.
+        try {
+            await handle.chmod(params.mode);
+        }
+        catch (error) {
+            await cleanupPinnedFilePath({
+                pathname: params.targetPath, handle, identity, parentGuard: params.parentGuard,
+            });
+            throw error;
+        }
+        if (params.options.durable !== false)
+            await handle.sync();
+        await verify();
+        if (params.options.durable !== false) {
+            await syncDirectoryBestEffort(path.dirname(params.targetPath));
+            if (compatibility)
+                await verify();
+        }
+    }
+    finally {
+        await accepted?.close().catch(() => undefined);
+    }
+}

package/dist/root-write-verification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-write-verification.d.ts","sourceRoot":"","sources":["../src/root-write-verification.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAK9F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhF,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,sBAAsB,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,sBAAsB,CAAC;CACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqFhB"}
+{"version":3,"file":"root-write-verification.d.ts","sourceRoot":"","sources":["../src/root-write-verification.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAK9F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIhF,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,sBAAsB,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,sBAAsB,CAAC;CACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAgGhB"}

package/dist/root-write-verification.js

@@ -4,10 +4,11 @@ import { assertAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { resolveOpenedFileRealPathForFd } from "./opened-realpath.js";
-import { assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path.js";
+import { assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError } from "./path.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { assertRootIdentityCurrent } from "./root-context.js";
 import { fileNotFoundError, hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
 export async function verifyAtomicWriteResult(params) {
     let needsPathOpen = false;
     const assertFile = (stat) => {
@@ -47,9 +48,15 @@ export async function verifyAtomicWriteResult(params) {
         // This descriptor remains owned by the writer, even when final mode forbids opens.
         const stat = assertDescriptor();
         assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
-        const { realPath } = await resolveOpenedFileRealPathForFd(params.fd, stat, params.targetPath);
-        assertPath(fsSync.statSync(realPath, { bigint: true }));
-        if (!isPathInside(params.root.rootWithSep, realPath)) {
+        const { realPath, stat: resolvedStat } = await resolveOpenedFileRealPathForFd(params.fd, stat, params.targetPath);
+        // Consume the resolver's observation only in this pass; the checks after
+        // the directory guards must still sample the current path and descriptor.
+        assertPath(resolvedStat);
+        if (!admitPathInsideRoot({
+            rootPath: params.root.rootReal,
+            candidatePath: realPath,
+            rootIdentity: params.root.rootIdentity,
+        })) {
             throw outsideWorkspaceError();
         }
         await assertAsyncDirectoryGuard(params.parentGuard);
@@ -74,9 +81,13 @@ export async function verifyAtomicWriteResult(params) {
             try {
                 const reopenedStat = assertDescriptor(opened.fd);
                 assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
-                const { realPath: reopenedPath } = await resolveOpenedFileRealPathForFd(opened.fd, reopenedStat, params.targetPath);
-                assertPath(fsSync.statSync(reopenedPath, { bigint: true }));
-                if (!isPathInside(params.root.rootWithSep, reopenedPath)) {
+                const { realPath: reopenedPath, stat: reopenedPathStat } = await resolveOpenedFileRealPathForFd(opened.fd, reopenedStat, params.targetPath);
+                assertPath(reopenedPathStat);
+                if (!admitPathInsideRoot({
+                    rootPath: params.root.rootReal,
+                    candidatePath: reopenedPath,
+                    rootIdentity: params.root.rootIdentity,
+                })) {
                     throw outsideWorkspaceError();
                 }
                 await assertAsyncDirectoryGuard(params.parentGuard);

package/dist/safe-path-segment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safe-path-segment.d.ts","sourceRoot":"","sources":["../src/safe-path-segment.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAaT;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAUR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAWR;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAeR"}
+{"version":3,"file":"safe-path-segment.d.ts","sourceRoot":"","sources":["../src/safe-path-segment.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAaT;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAUR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAWR;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAeR"}

package/dist/safe-path-segment.js

@@ -4,12 +4,14 @@ const SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
 // Windows treats "C:name" as relative to the drive's current directory even
 // though path.win32.isAbsolute() reports false.
 const DRIVE_RELATIVE_PREFIX = /^[A-Za-z]:(?![\\/])/;
+// A forward slash ends the segment, so "C:/file" still contains the "C:" segment.
+const DRIVE_RELATIVE_SEGMENT = /(?:^|\/)[A-Za-z]:(?!\\)/;
 const HYPHEN_CHAR_CODE = 0x2d;
 export function isDriveRelativePath(value) {
     return DRIVE_RELATIVE_PREFIX.test(value);
 }
 export function assertNoDriveRelativePathSegments(value, label) {
-    if (value.split("/").some(isDriveRelativePath)) {
+    if (DRIVE_RELATIVE_SEGMENT.test(value)) {
         throw new FsSafeError("invalid-path", `${label} must not contain a drive letter`);
     }
     return value;

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;AAUhJ,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAIjC,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,CAkER;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;AAYF,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,CAuBD;AAwDD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}
+{"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;AAUhJ,OAAO,EAML,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,CAmER;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"}

package/dist/secret-file.js

@@ -17,32 +17,36 @@ import { verifyAtomicWriteResult } from "./root-write-verification.js";
 import { assertSecretFilePreview, resolveSecretReadPolicy, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { serializePathWrite } from "./write-queue.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 export const PRIVATE_SECRET_DIR_MODE = 0o700;
 export const PRIVATE_SECRET_FILE_MODE = 0o600;
 export function readSecretFileSync(filePath, label, options = {}) {
     const { resolvedPath, maxBytes } = resolveSecretReadPolicy(filePath, label, options);
-    function inspectInput(symlinkMessage) {
-        const stat = options.rejectSymlink
-            ? fs.lstatSync(resolvedPath, { bigint: true })
-            : fs.statSync(resolvedPath, { bigint: true });
-        if (options.rejectSymlink && stat.isSymbolicLink()) {
-            throw new FsSafeError("symlink", symlinkMessage);
-        }
-        return stat;
-    }
+    let rejectSymlink;
     let previewStat;
     try {
         assertNoUnsafeDeviceReadPath(resolvedPath);
+        rejectSymlink = Boolean(options.rejectSymlink);
         previewStat = inspectFileIdentitySync(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
     }
     catch (error) {
         throw secretReadError(error instanceof FsSafeError ? error.code : secretPathErrorCode(error), "inspect", label, resolvedPath, error);
     }
-    assertSecretFilePreview(previewStat, label, resolvedPath, maxBytes, options.rejectHardlinks !== false);
+    function inspectInput(symlinkMessage) {
+        const stat = rejectSymlink
+            ? fs.lstatSync(resolvedPath, { bigint: true })
+            : fs.statSync(resolvedPath, { bigint: true });
+        if (rejectSymlink && stat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", symlinkMessage);
+        }
+        return stat;
+    }
+    const rejectHardlinks = options.rejectHardlinks !== false;
+    assertSecretFilePreview(previewStat, label, resolvedPath, maxBytes, rejectHardlinks);
     const opened = openPinnedFileSync({
         filePath: resolvedPath,
-        rejectPathSymlink: options.rejectSymlink,
-        rejectHardlinks: options.rejectHardlinks !== false,
+        rejectPathSymlink: rejectSymlink,
+        rejectHardlinks,
     });
     if (!opened.ok) {
         throw secretReadError(opened.reason === "path" ? "not-found" : "path-mismatch", "read", label, resolvedPath, opened.reason === "validation" ? new Error("security validation failed") : opened.error);
@@ -51,14 +55,14 @@ export function readSecretFileSync(filePath, label, options = {}) {
     try {
         const openedIdentity = inspectFileIdentitySync(() => {
             const stat = fs.fstatSync(opened.fd, { bigint: true });
-            if (!stat.isFile() || (options.rejectHardlinks !== false && stat.nlink > 1n)) {
+            if (!stat.isFile() || (rejectHardlinks && stat.nlink > 1n)) {
                 throw new FsSafeError("path-mismatch", "security validation failed");
             }
             return stat;
         }, previewStat);
         inspectFileIdentitySync(() => {
             const stat = fs.lstatSync(opened.path, { bigint: true });
-            if (!stat.isFile() || (options.rejectHardlinks !== false && stat.nlink > 1n)) {
+            if (!stat.isFile() || (rejectHardlinks && stat.nlink > 1n)) {
                 throw new FsSafeError("path-mismatch", "security validation failed");
             }
             return stat;
@@ -152,8 +156,8 @@ async function inspectPrivateDirectory(directory, kind) {
     });
 }
 async function ensurePrivateDirectory(rootDir, targetDir, mode) {
-    const resolvedRoot = path.resolve(rootDir);
-    const resolvedTarget = path.resolve(targetDir);
+    const resolvedRoot = resolvePathPreservingWindowsRoot(rootDir);
+    const resolvedTarget = resolvePathPreservingWindowsRoot(targetDir);
     let rootStat = await inspectPrivateDirectory(resolvedRoot, "root").catch((error) => {
         if (error.code !== "ENOENT")
             throw error;
@@ -228,21 +232,42 @@ async function ensurePrivateDirectory(rootDir, targetDir, mode) {
     }
     return { rootGuard, parentGuard: targetGuard };
 }
+function snapshotSecretFileWriteParams(params, rootDir, filePath) {
+    return {
+        rootDir,
+        filePath,
+        content: params.content,
+        mode: params.mode,
+        dirMode: params.dirMode,
+        durable: params.durable,
+    };
+}
 async function secretFileWriteQueueKey(filePath) {
+    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     try {
         return await canonicalPathFromExistingAncestor(filePath);
     }
-    catch {
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "invalid-path")
+            throw error;
         // Keep validation and its public error shape owned by the write path below.
-        return path.resolve(filePath);
+        const resolved = path.resolve(filePath);
+        assertNoWindowsPathAlias(resolved, "filesystem", "private secret path uses a Windows filesystem namespace alias");
+        return resolved;
     }
 }
 // Internal preparation for private writers and their pre-write locks; not lasting authorization.
 export async function prepareSecretFileWrite(params) {
+    const rootDir = params.rootDir;
+    const filePath = params.filePath;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     const mode = params.mode ?? PRIVATE_SECRET_FILE_MODE;
     const dirMode = params.dirMode ?? PRIVATE_SECRET_DIR_MODE;
-    const resolvedRoot = path.resolve(params.rootDir);
-    const resolvedFile = path.resolve(params.filePath);
+    const resolvedRoot = resolvePathPreservingWindowsRoot(rootDir);
+    const resolvedFile = path.resolve(filePath);
+    assertNoWindowsPathAlias(resolvedRoot, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(resolvedFile, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     assertPathWithinRoot(resolvedRoot, resolvedFile);
     for (const [kind, value] of [["file", mode], ["directory", dirMode]]) {
         if (!Number.isInteger(value) || value < 0 || value > 0o7777) {
@@ -254,8 +279,11 @@ export async function prepareSecretFileWrite(params) {
     await assertAsyncDirectoryGuard(rootGuard);
     await assertAsyncDirectoryGuard(parentGuard);
     assertRealPathWithinRoot(rootGuard.realPath, parentGuard.realPath);
+    assertNoWindowsPathAlias(rootGuard.realPath, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(parentGuard.realPath, "filesystem", "private secret parent uses a Windows filesystem namespace alias");
     const fileName = path.basename(resolvedFile);
     const finalFilePath = path.join(parentGuard.realPath, fileName);
+    assertNoWindowsPathAlias(finalFilePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     return { mode, rootGuard, parentGuard, fileName, finalFilePath };
 }
 async function materializeSecretFileAtomic(params, createOnly) {
@@ -309,16 +337,26 @@ async function materializeSecretFileAtomic(params, createOnly) {
     });
 }
 export async function writeSecretFileAtomic(params) {
-    const canonicalPath = await secretFileWriteQueueKey(params.filePath);
+    const rootDir = params.rootDir;
+    const filePath = params.filePath;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
+    const ownedParams = snapshotSecretFileWriteParams(params, rootDir, filePath);
+    const canonicalPath = await secretFileWriteQueueKey(filePath);
     await serializePathWrite(canonicalPath, async () => {
-        await materializeSecretFileAtomic(params, false);
+        await materializeSecretFileAtomic(ownedParams, false);
     });
 }
 export async function createSecretFileAtomic(params) {
     try {
-        const canonicalPath = await secretFileWriteQueueKey(params.filePath);
+        const rootDir = params.rootDir;
+        const filePath = params.filePath;
+        assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+        assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
+        const ownedParams = snapshotSecretFileWriteParams(params, rootDir, filePath);
+        const canonicalPath = await secretFileWriteQueueKey(filePath);
         await serializePathWrite(canonicalPath, async () => {
-            await materializeSecretFileAtomic(params, true);
+            await materializeSecretFileAtomic(ownedParams, true);
         });
     }
     catch (error) {

package/dist/secret-read-async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAQA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA0DjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}
+{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAQA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAGjC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA6DjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}

package/dist/secret-read-async.js

@@ -5,38 +5,43 @@ import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { realpathSync } from "./realpath.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertSecretFilePreview, resolveSecretReadPolicy, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export async function readSecretFile(filePath, label, options = {}) {
     const { resolvedPath, maxBytes } = resolveSecretReadPolicy(filePath, label, options);
-    async function inspectInput(symlinkMessage) {
-        const stat = options.rejectSymlink
-            ? fsSync.lstatSync(resolvedPath, { bigint: true })
-            : fsSync.statSync(resolvedPath, { bigint: true });
-        if (options.rejectSymlink && stat.isSymbolicLink()) {
-            throw new FsSafeError("symlink", symlinkMessage);
-        }
-        return stat;
-    }
+    let rejectSymlink;
     let previewStat;
     try {
         assertNoUnsafeDeviceReadPath(resolvedPath);
-        previewStat = await inspectFileIdentity(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
+        rejectSymlink = Boolean(options.rejectSymlink);
+        previewStat = inspectFileIdentitySync(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
     }
     catch (error) {
         throw secretReadError(error instanceof FsSafeError ? error.code : secretPathErrorCode(error), "inspect", label, resolvedPath, error);
     }
-    assertSecretFilePreview(previewStat, label, resolvedPath, maxBytes, options.rejectHardlinks !== false);
+    function inspectInput(symlinkMessage) {
+        const stat = rejectSymlink
+            ? fsSync.lstatSync(resolvedPath, { bigint: true })
+            : fsSync.statSync(resolvedPath, { bigint: true });
+        if (rejectSymlink && stat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", symlinkMessage);
+        }
+        return stat;
+    }
+    const rejectHardlinks = options.rejectHardlinks !== false;
+    assertSecretFilePreview(previewStat, label, resolvedPath, maxBytes, rejectHardlinks);
     let handle;
     let raw;
     try {
         const realPath = realpathSync.native(resolvedPath);
+        assertNoWindowsPathAlias(realPath, "filesystem", `${label} file path uses a Windows filesystem namespace alias`);
         assertNoUnsafeDeviceReadPath(realPath);
         handle = await fs.open(realPath, resolveReadOpenFlags());
         const openedHandle = handle;
         const openedStat = await inspectFileIdentity(async () => {
             const stat = fsSync.fstatSync(openedHandle.fd, { bigint: true });
-            if (!stat.isFile() || (options.rejectHardlinks !== false && stat.nlink > 1n)) {
+            if (!stat.isFile() || (rejectHardlinks && stat.nlink > 1n)) {
                 throw new FsSafeError("path-mismatch", "security validation failed");
             }
             return stat;

package/dist/secret-read-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-read-policy.d.ts","sourceRoot":"","sources":["../src/secret-read-policy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,6BAA6B,QAAY,CAAC;AAEvD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAGnE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,GAAG,MAAM,EAC1B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,OAAO,GACb,WAAW,CAGb;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,OAAO,GACvB,IAAI,CAUN;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAM9F;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG;IACxG,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,CASA"}
+{"version":3,"file":"secret-read-policy.d.ts","sourceRoot":"","sources":["../src/secret-read-policy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAGhE,eAAO,MAAM,6BAA6B,QAAY,CAAC;AAEvD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAGnE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,GAAG,MAAM,EAC1B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,OAAO,GACb,WAAW,CAGb;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,OAAO,GACvB,IAAI,CAUN;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAM9F;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG;IACxG,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAYA"}

package/dist/secret-read-policy.js

@@ -1,6 +1,7 @@
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
 import { FsSafeError } from "./errors.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
 export function secretPathErrorCode(error) {
     const code = error.code;
@@ -29,10 +30,13 @@ export function trimSecretFileContent(raw, label, resolvedPath) {
     return secret;
 }
 export function resolveSecretReadPolicy(filePath, label, options) {
-    const resolvedPath = resolveHomeRelativePath(filePath.trim());
+    const trimmedPath = filePath.trim();
+    assertNoWindowsPathAlias(trimmedPath, "filesystem", `${label} file path uses a Windows filesystem namespace alias`);
+    const resolvedPath = resolveHomeRelativePath(trimmedPath);
     if (!resolvedPath) {
         throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
     }
+    assertNoWindowsPathAlias(resolvedPath, "filesystem", `${label} file path uses a Windows filesystem namespace alias`);
     const maxBytes = normalizeMaxBytes(options.maxBytes, {
         defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
     });

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

@@ -0,0 +1,10 @@
+import type { BigIntStats, Stats } from "node:fs";
+import type { PermissionCheck } from "./permissions.js";
+type ExactIdentity = Pick<BigIntStats, "dev" | "ino">;
+export declare function inspectSecureWindowsDescriptor(params: {
+    fd: number;
+    identity: ExactIdentity;
+    stat: Stats;
+}): PermissionCheck;
+export {};
+//# sourceMappingURL=secure-file-windows.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secure-file-windows.d.ts","sourceRoot":"","sources":["../src/secure-file-windows.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AASlD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AA4BxD,KAAK,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AAuHtD,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,KAAK,CAAC;CACb,GAAG,eAAe,CA0ClB"}