@openclaw/fs-safe 0.8.2 → 0.8.4

package/dist/root-path.js

@@ -1,13 +1,11 @@
 import fs from "node:fs";
-import fsp from "node:fs/promises";
 import path from "node:path";
-import { formatErrorDetail } from "./error-detail.js";
+import { formatErrorDetail, shortPath } from "./error-detail.js";
 import { FsSafeError } from "./errors.js";
 import { assertNoNulPathInput, isNotFoundPathError, isPathInside, isPathRelativeEscape, } from "./path.js";
 import { resolvePathViaExistingAncestor, resolvePathViaExistingAncestorSync, } from "./root-path-existing.js";
 import { resolveSymlinkHopPath, resolveSymlinkHopPathSync } from "./root-path-symlink.js";
 import { assertNoDriveRelativePathSegments } from "./safe-path-segment.js";
-import { shortPath } from "./short-path.js";
 export { resolvePathViaExistingAncestorSync } from "./root-path-existing.js";
 export const ROOT_PATH_ALIAS_POLICIES = {
     strict: Object.freeze({
@@ -120,12 +118,6 @@ function assertNoEmbeddedDriveRelativeSegment(filePath, label) {
     const root = path.parse(filePath).root;
     assertNoDriveRelativePathSegments(filePath.slice(root.length).replaceAll("\\", "/"), label);
 }
-function isPromiseLike(value) {
-    return Boolean(value &&
-        (typeof value === "object" || typeof value === "function") &&
-        "then" in value &&
-        typeof value.then === "function");
-}
 function createLexicalTraversalState(params) {
     const rawAbsolutePath = params.params.absolutePath;
     const rawRelativePath = rawPathRelativeToRoot(params.rootPath, rawAbsolutePath);
@@ -205,26 +197,13 @@ function handleLexicalLstatFailure(context, error, missingFromIndex) {
     applyMissingSuffixToCanonicalCursor(context, missingFromIndex);
     return true;
 }
-function handleLexicalStatReadFailure(context, error, missingFromIndex) {
-    if (handleLexicalLstatFailure(context, error, missingFromIndex)) {
-        return null;
-    }
-    throw error;
-}
-function handleLexicalStatDisposition(context, params) {
-    if (!params.isSymbolicLink) {
-        advanceCanonicalCursorForSegment(context, params.segment);
+function lexicalStatDisposition(params) {
+    if (!params.isSymbolicLink)
         return "continue";
-    }
-    if (context.resolveParams.rejectSymlinks === true && params.isLast) {
+    if (params.rejectSymlinks === true && params.isLast) {
         throw new FsSafeError("symlink", "symlink path component not allowed");
     }
-    if (context.state.allowFinalSymlink && params.isLast) {
-        context.state.preserveFinalSymlink = true;
-        advanceCanonicalCursorForSegment(context, params.segment);
-        return "break";
-    }
-    return "resolve-link";
+    return params.allowFinalSymlink && params.isLast ? "break" : "resolve-link";
 }
 function applyResolvedSymlinkHop(context, linkCanonical) {
     if (!isPathInside(context.rootCanonicalPath, linkCanonical)) {
@@ -237,70 +216,48 @@ function applyResolvedSymlinkHop(context, linkCanonical) {
     context.state.canonicalCursor = linkCanonical;
     context.state.lexicalCursor = linkCanonical;
 }
-function readLexicalStat(context, params) {
-    try {
-        const stat = params.read(context.state.lexicalCursor);
-        if (isPromiseLike(stat)) {
-            return Promise.resolve(stat).catch((error) => handleLexicalStatReadFailure(context, error, params.missingFromIndex));
-        }
-        return stat;
-    }
-    catch (error) {
-        return handleLexicalStatReadFailure(context, error, params.missingFromIndex);
-    }
-}
-function resolveAndApplySymlinkHop(context, params) {
-    const linkCanonical = params.resolveLinkCanonical(context.state.lexicalCursor);
-    if (isPromiseLike(linkCanonical)) {
-        return Promise.resolve(linkCanonical).then((value) => {
-            applyResolvedSymlinkHop(context, value);
-        });
-    }
-    applyResolvedSymlinkHop(context, linkCanonical);
-}
 function applyParentTraversalStep(context) {
     context.state.lexicalCursor = path.resolve(context.state.lexicalCursor, "..");
     advanceCanonicalCursorForSegment(context, "..");
 }
-function* iterateLexicalTraversal(state) {
-    for (let idx = 0; idx < state.segments.length; idx += 1) {
-        const segment = state.segments[idx] ?? "";
-        const isLast = idx === state.segments.length - 1;
-        yield { idx, segment, isLast };
-    }
-}
 async function resolveRootPathLexicalAsync(params) {
     const context = createLexicalTraversalContext(params);
     const { state } = context;
-    for (const { idx, segment, isLast } of iterateLexicalTraversal(state)) {
+    for (let idx = 0; idx < state.segments.length; idx += 1) {
+        const segment = state.segments[idx] ?? "";
+        const isLast = idx === state.segments.length - 1;
         if (segment === "..") {
             applyParentTraversalStep(context);
             continue;
         }
         state.lexicalCursor = path.join(state.lexicalCursor, segment);
-        const stat = await readLexicalStat(context, {
-            missingFromIndex: idx,
-            read: (cursor) => fsp.lstat(cursor),
-        });
-        if (!stat) {
-            break;
+        let stat;
+        try {
+            stat = fs.lstatSync(state.lexicalCursor);
         }
-        const disposition = handleLexicalStatDisposition(context, {
-            isSymbolicLink: stat.isSymbolicLink(),
-            segment,
+        catch (error) {
+            if (handleLexicalLstatFailure(context, error, idx))
+                break;
+            throw error;
+        }
+        const isSymbolicLink = stat.isSymbolicLink();
+        const disposition = lexicalStatDisposition({
+            isSymbolicLink,
             isLast,
+            rejectSymlinks: isSymbolicLink ? context.resolveParams.rejectSymlinks : undefined,
+            allowFinalSymlink: state.allowFinalSymlink,
         });
-        if (disposition === "continue") {
+        if (disposition !== "resolve-link") {
+            state.preserveFinalSymlink = disposition === "break";
+            advanceCanonicalCursorForSegment(context, segment);
+            if (state.preserveFinalSymlink)
+                break;
             continue;
         }
-        if (disposition === "break") {
-            break;
-        }
-        await resolveAndApplySymlinkHop(context, {
-            resolveLinkCanonical: (cursor) => resolveSymlinkHopPath(cursor, {
-                rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
-            }),
+        const linkCanonical = await resolveSymlinkHopPath(state.lexicalCursor, {
+            rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
         });
+        applyResolvedSymlinkHop(context, linkCanonical);
         if (context.resolveParams.rejectSymlinks === true) {
             throw new FsSafeError("symlink", "symlink path component not allowed");
         }
@@ -319,36 +276,33 @@ function resolveRootPathLexicalSync(params) {
             continue;
         }
         state.lexicalCursor = path.join(state.lexicalCursor, segment);
-        const maybeStat = readLexicalStat(context, {
-            missingFromIndex: idx,
-            read: (cursor) => fs.lstatSync(cursor),
-        });
-        if (isPromiseLike(maybeStat)) {
-            throw new Error("Unexpected async lexical stat");
+        let stat;
+        try {
+            stat = fs.lstatSync(state.lexicalCursor);
         }
-        const stat = maybeStat;
-        if (!stat) {
-            break;
+        catch (error) {
+            if (handleLexicalLstatFailure(context, error, idx))
+                break;
+            throw error;
         }
-        const disposition = handleLexicalStatDisposition(context, {
-            isSymbolicLink: stat.isSymbolicLink(),
-            segment,
+        const isSymbolicLink = stat.isSymbolicLink();
+        const disposition = lexicalStatDisposition({
+            isSymbolicLink,
             isLast,
+            rejectSymlinks: isSymbolicLink ? context.resolveParams.rejectSymlinks : undefined,
+            allowFinalSymlink: state.allowFinalSymlink,
         });
-        if (disposition === "continue") {
+        if (disposition !== "resolve-link") {
+            state.preserveFinalSymlink = disposition === "break";
+            advanceCanonicalCursorForSegment(context, segment);
+            if (state.preserveFinalSymlink)
+                break;
             continue;
         }
-        if (disposition === "break") {
-            break;
-        }
-        const maybeApplied = resolveAndApplySymlinkHop(context, {
-            resolveLinkCanonical: (cursor) => resolveSymlinkHopPathSync(cursor, {
-                rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
-            }),
+        const linkCanonical = resolveSymlinkHopPathSync(state.lexicalCursor, {
+            rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
         });
-        if (isPromiseLike(maybeApplied)) {
-            throw new Error("Unexpected async symlink resolution");
-        }
+        applyResolvedSymlinkHop(context, linkCanonical);
         if (context.resolveParams.rejectSymlinks === true) {
             throw new FsSafeError("symlink", "symlink path component not allowed");
         }
@@ -468,8 +422,8 @@ function buildResolvedRootPath(params) {
 async function getPathKind(absolutePath, preserveFinalSymlink) {
     try {
         const stat = preserveFinalSymlink
-            ? await fsp.lstat(absolutePath)
-            : await fsp.stat(absolutePath);
+            ? fs.lstatSync(absolutePath)
+            : fs.statSync(absolutePath);
         return { exists: true, kind: toResolvedKind(stat) };
     }
     catch (error) {

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

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

package/dist/root-paths.js

@@ -1,3 +1,4 @@
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { formatErrorDetail } from "./error-detail.js";
@@ -16,7 +17,7 @@ function pathStaysWithinRoot(rootDir, candidatePath) {
 }
 async function resolveRealPathIfExists(targetPath) {
     try {
-        return await fs.realpath(targetPath);
+        return fsSync.realpathSync.native(targetPath);
     }
     catch {
         return undefined;
@@ -24,11 +25,11 @@ async function resolveRealPathIfExists(targetPath) {
 }
 async function resolveTrustedRootRealPath(rootDir) {
     try {
-        const rootLstat = await fs.lstat(rootDir);
+        const rootLstat = fsSync.lstatSync(rootDir);
         if (!rootLstat.isDirectory() || rootLstat.isSymbolicLink()) {
             return undefined;
         }
-        return await fs.realpath(rootDir);
+        return fsSync.realpathSync.native(rootDir);
     }
     catch {
         return undefined;
@@ -36,7 +37,7 @@ async function resolveTrustedRootRealPath(rootDir) {
 }
 async function validateCanonicalPathWithinRoot(params) {
     try {
-        const candidateLstat = await fs.lstat(params.candidatePath);
+        const candidateLstat = fsSync.lstatSync(params.candidatePath);
         if (candidateLstat.isSymbolicLink()) {
             return "invalid";
         }
@@ -49,7 +50,7 @@ async function validateCanonicalPathWithinRoot(params) {
         if (params.expect === "file" && candidateLstat.nlink > 1) {
             return "invalid";
         }
-        const candidateRealPath = await fs.realpath(params.candidatePath);
+        const candidateRealPath = fsSync.realpathSync.native(params.candidatePath);
         return isPathInside(params.rootRealPath, candidateRealPath) ? "ok" : "invalid";
     }
     catch (err) {
@@ -109,7 +110,7 @@ async function resolveNearestExistingPath(targetPath) {
     let current = path.resolve(targetPath);
     while (true) {
         try {
-            await fs.lstat(current);
+            fsSync.lstatSync(current);
             return current;
         }
         catch (err) {
@@ -133,7 +134,7 @@ async function assertNoSymlinkSegments(params) {
     for (const segment of relative.split(path.sep).filter(Boolean)) {
         current = path.join(current, segment);
         try {
-            const stat = await fs.lstat(current);
+            const stat = fsSync.lstatSync(current);
             if (stat.isSymbolicLink()) {
                 throw new FsSafeError("symlink", `Invalid path: must not traverse symlinks within ${params.scopeLabel}`);
             }
@@ -163,14 +164,14 @@ export async function ensureDirectoryWithinRoot(params) {
             return lexical;
         const rootDir = path.resolve(params.rootDir);
         const targetPath = lexical.path;
-        const rootStat = await fs.lstat(rootDir);
+        const rootStat = fsSync.lstatSync(rootDir);
         if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
             return invalidPath(scopeLabel);
         }
         await assertNoSymlinkSegments({ rootDir, targetPath, scopeLabel });
-        const rootReal = await fs.realpath(rootDir);
+        const rootReal = fsSync.realpathSync.native(rootDir);
         const nearestExistingPath = await resolveNearestExistingPath(targetPath);
-        const nearestExistingReal = await fs.realpath(nearestExistingPath);
+        const nearestExistingReal = fsSync.realpathSync.native(nearestExistingPath);
         if (!isPathInside(rootReal, nearestExistingReal)) {
             return invalidPath(scopeLabel);
         }
@@ -180,7 +181,7 @@ export async function ensureDirectoryWithinRoot(params) {
             current = path.join(current, segment);
             while (true) {
                 try {
-                    const stat = await fs.lstat(current);
+                    const stat = fsSync.lstatSync(current);
                     if (stat.isSymbolicLink() || !stat.isDirectory()) {
                         return invalidPath(scopeLabel);
                     }
@@ -201,12 +202,12 @@ export async function ensureDirectoryWithinRoot(params) {
                     }
                 }
             }
-            const currentReal = await fs.realpath(current);
+            const currentReal = fsSync.realpathSync.native(current);
             if (!isPathInside(rootReal, currentReal)) {
                 return invalidPath(scopeLabel);
             }
         }
-        const targetReal = await fs.realpath(targetPath);
+        const targetReal = fsSync.realpathSync.native(targetPath);
         if (!isPathInside(rootReal, targetReal)) {
             return invalidPath(scopeLabel);
         }
@@ -308,7 +309,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
             return lexicalPathResult;
         }
         try {
-            const resolvedExistingPath = await fs.realpath(raw);
+            const resolvedExistingPath = fsSync.realpathSync.native(raw);
             const relativePath = path.relative(rootRealPath, resolvedExistingPath);
             if (!isInRoot(relativePath)) {
                 return lexicalPathResult;
@@ -350,7 +351,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
                         scopeLabel: params.scopeLabel,
                     });
                     const existingPath = await resolveNearestExistingPath(pathResult.fallbackPath);
-                    const existingRealPath = await fs.realpath(existingPath);
+                    const existingRealPath = fsSync.realpathSync.native(existingPath);
                     if (!isPathInside(rootRealPath, existingRealPath)) {
                         return invalidPath(params.scopeLabel);
                     }

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

@@ -0,0 +1,6 @@
+export declare function inheritWriteTargetMode(params: {
+    targetPath: string;
+    rootWithSep: string;
+    requestedMode?: number;
+}): Promise<number>;
+//# sourceMappingURL=root-write-mode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"root-write-mode.d.ts","sourceRoot":"","sources":["../src/root-write-mode.ts"],"names":[],"mappings":"AAUA,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB"}

package/dist/root-write-mode.js

@@ -0,0 +1,61 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { isNotFoundPathError, isPathInside } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.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 }));
+        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());
+        try {
+            // Bind admission to the inode whose metadata is inherited.
+            if (!sameFileIdentity(fsSync.fstatSync(handle.fd, { bigint: true }), existing)) {
+                throw new FsSafeError("path-mismatch", "write target changed during mode inheritance");
+            }
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+        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 = fsSync.realpathSync.native(params.targetPath);
+            if (!isPathInside(params.rootWithSep, realPath))
+                throw outsideWorkspaceError();
+            await inspectFileIdentity(async () => {
+                const current = fsSync.statSync(realPath, { bigint: true });
+                if (!current.isFile())
+                    throw new FsSafeError("not-file", "not a file");
+                if (current.nlink > 1n)
+                    throw hardlinkedPathNotAllowedError();
+                return current;
+            }, existing);
+        }
+        catch (error) {
+            if (isNotFoundPathError(error)) {
+                throw new FsSafeError("path-mismatch", "write target changed during mode inheritance", { cause: error });
+            }
+            throw error;
+        }
+        return params.requestedMode ?? Number(existing.mode & 511n);
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
+        return params.requestedMode ?? 0o600;
+    }
+}

package/dist/root-write-verification.js

@@ -46,16 +46,16 @@ export async function verifyAtomicWriteResult(params) {
     try {
         // This descriptor remains owned by the writer, even when final mode forbids opens.
         const stat = assertDescriptor();
-        assertPath(await fs.lstat(params.targetPath, { bigint: true }));
-        const realPath = await resolveOpenedFileRealPathForFd(params.fd, stat, params.targetPath);
-        assertPath(await fs.stat(realPath, { bigint: true }));
+        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)) {
             throw outsideWorkspaceError();
         }
         await assertAsyncDirectoryGuard(params.parentGuard);
         await assertRootIdentityCurrent(params.root);
         // Recheck after canonical resolution and directory checks, including late links.
-        assertPath(await fs.lstat(params.targetPath, { bigint: true }));
+        assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
         assertDescriptor();
         if (needsPathOpen) {
             // A retained fd cannot prove that an opaque Windows pathname still names it.
@@ -73,15 +73,15 @@ export async function verifyAtomicWriteResult(params) {
             });
             try {
                 const reopenedStat = assertDescriptor(opened.fd);
-                assertPath(await fs.lstat(params.targetPath, { bigint: true }));
-                const reopenedPath = await resolveOpenedFileRealPathForFd(opened.fd, reopenedStat, params.targetPath);
-                assertPath(await fs.stat(reopenedPath, { bigint: true }));
+                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)) {
                     throw outsideWorkspaceError();
                 }
                 await assertAsyncDirectoryGuard(params.parentGuard);
                 await assertRootIdentityCurrent(params.root);
-                assertPath(await fs.lstat(params.targetPath, { bigint: true }));
+                assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
                 assertDescriptor(opened.fd);
             }
             finally {

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

@@ -4,6 +4,7 @@ export type SafePathSegmentOptions = {
 };
 export declare function isDriveRelativePath(value: string): boolean;
 export declare function assertNoDriveRelativePathSegments(value: string, label: string): string;
+export declare function trimHyphenEdges(value: string): string;
 export declare function isSafePathSegment(segment: string, options?: SafePathSegmentOptions): boolean;
 export declare function assertSafePathSegment(segment: string, options?: SafePathSegmentOptions): string;
 export declare function sanitizeSafePathSegment(value: string, fallback: string, options?: SafePathSegmentOptions): string;

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;AAcD,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":"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"}

package/dist/safe-path-segment.js

@@ -14,7 +14,7 @@ export function assertNoDriveRelativePathSegments(value, label) {
     }
     return value;
 }
-function trimHyphenEdges(value) {
+export function trimHyphenEdges(value) {
     let start = 0;
     let end = value.length;
     while (start < end && value.charCodeAt(start) === HYPHEN_CHAR_CODE) {

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,CAyER;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;CAClB,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;AAuDD,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;AAK/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;CAClB,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;AAuDD,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"}

package/dist/secret-file.js

@@ -3,7 +3,6 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
-import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
 import { assertOwnedDirectory } from "./directory-mode-owner.js";
@@ -14,19 +13,13 @@ import { openPinnedFileSync } from "./pinned-open.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
 import { ensureTrailingSep } from "./root-context.js";
 import { verifyAtomicWriteResult } from "./root-write-verification.js";
-import { assertSecretFilePreview, DEFAULT_SECRET_FILE_MAX_BYTES, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.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";
 export const PRIVATE_SECRET_DIR_MODE = 0o700;
 export const PRIVATE_SECRET_FILE_MODE = 0o600;
 export function readSecretFileSync(filePath, label, options = {}) {
-    const resolvedPath = resolveHomeRelativePath(filePath.trim());
-    if (!resolvedPath) {
-        throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
-    }
-    const maxBytes = normalizeMaxBytes(options.maxBytes, {
-        defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
-    });
+    const { resolvedPath, maxBytes } = resolveSecretReadPolicy(filePath, label, options);
     function inspectInput(symlinkMessage) {
         const stat = options.rejectSymlink
             ? fs.lstatSync(resolvedPath, { bigint: true })
@@ -147,7 +140,7 @@ async function enforcePrivateDirectoryMode(params) {
 }
 async function inspectPrivateDirectory(directory, kind) {
     return await inspectFileIdentity(async () => {
-        const stat = await fsp.lstat(directory, { bigint: true });
+        const stat = fs.lstatSync(directory, { bigint: true });
         if (stat.isSymbolicLink()) {
             throw new Error(`Private secret ${kind} ${directory} must not be a symlink.`);
         }
@@ -267,7 +260,7 @@ export async function prepareSecretFileWrite(params) {
 async function materializeSecretFileAtomic(params, createOnly) {
     const { mode, rootGuard, parentGuard, fileName, finalFilePath } = await prepareSecretFileWrite(params);
     try {
-        const stat = await fsp.lstat(finalFilePath);
+        const stat = fs.lstatSync(finalFilePath);
         if (createOnly) {
             throw new FsSafeError("secret-exists", `Private secret file ${finalFilePath} already exists.`);
         }

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":"AASA,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,CAgEjB;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":"AAOA,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"}

package/dist/secret-read-async.js

@@ -1,21 +1,13 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { readFileHandleBounded } from "./bounded-read.js";
-import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
-import { resolveHomeRelativePath } from "./home-dir.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
-import { assertSecretFilePreview, DEFAULT_SECRET_FILE_MAX_BYTES, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
+import { assertSecretFilePreview, resolveSecretReadPolicy, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
 export async function readSecretFile(filePath, label, options = {}) {
-    const resolvedPath = resolveHomeRelativePath(filePath.trim());
-    if (!resolvedPath) {
-        throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
-    }
-    const maxBytes = normalizeMaxBytes(options.maxBytes, {
-        defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
-    });
+    const { resolvedPath, maxBytes } = resolveSecretReadPolicy(filePath, label, options);
     async function inspectInput(symlinkMessage) {
         const stat = options.rejectSymlink
             ? await fs.lstat(resolvedPath, { bigint: true })

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

@@ -10,4 +10,8 @@ export declare function secretPathErrorCode(error: unknown): FsSafeErrorCode;
 export declare function secretReadError(code: FsSafeErrorCode, action: "inspect" | "read", label: string, resolvedPath: string, error: unknown): FsSafeError;
 export declare function assertSecretFilePreview(stat: BigIntStats, label: string, resolvedPath: string, maxBytes: number, rejectHardlinks: boolean): void;
 export declare function trimSecretFileContent(raw: string, label: string, resolvedPath: string): string;
+export declare function resolveSecretReadPolicy(filePath: string, label: string, options: SecretFileReadOptions): {
+    resolvedPath: string;
+    maxBytes: number;
+};
 //# sourceMappingURL=secret-read-policy.d.ts.map

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":"AAAA,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"}
+{"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"}

package/dist/secret-read-policy.js

@@ -1,3 +1,5 @@
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { resolveHomeRelativePath } from "./home-dir.js";
 import { FsSafeError } from "./errors.js";
 export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
 export function secretPathErrorCode(error) {
@@ -26,3 +28,13 @@ export function trimSecretFileContent(raw, label, resolvedPath) {
     }
     return secret;
 }
+export function resolveSecretReadPolicy(filePath, label, options) {
+    const resolvedPath = resolveHomeRelativePath(filePath.trim());
+    if (!resolvedPath) {
+        throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
+    }
+    const maxBytes = normalizeMaxBytes(options.maxBytes, {
+        defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
+    });
+    return { resolvedPath, maxBytes };
+}

package/dist/sibling-staged-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sibling-staged-file.d.ts","sourceRoot":"","sources":["../src/sibling-staged-file.ts"],"names":[],"mappings":"AAkCA,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CA6G3C"}
+{"version":3,"file":"sibling-staged-file.d.ts","sourceRoot":"","sources":["../src/sibling-staged-file.ts"],"names":[],"mappings":"AAmCA,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CAyG3C"}