@openclaw/fs-safe 0.19.0 → 0.20.0

package/dist/regular-file.js

@@ -208,10 +208,10 @@ function inspectAppendPath(filePath) {
 }
 function prepareRegularAppend(filePath, rejectSymlinkParents) {
     if (rejectSymlinkParents === true) {
-        const resolvedDir = resolvePathPreservingWindowsRoot(path.dirname(filePath));
+        const unresolvedDir = path.dirname(filePath);
         assertNoSymlinkParentsSync({
-            rootDir: path.parse(resolvedDir).root,
-            targetPath: resolvedDir,
+            rootDir: path.parse(resolvePathPreservingWindowsRoot(unresolvedDir)).root,
+            targetPath: unresolvedDir,
             allowMissing: false,
             allowRootChildSymlink: true,
             requireDirectories: true,

package/dist/replace-file-copy-fallback.d.ts

@@ -9,9 +9,8 @@ type AsyncFallbackFs = {
     lstat: typeof import("node:fs/promises").lstat;
     open: typeof import("node:fs/promises").open;
     rm: typeof import("node:fs/promises").rm;
-    unlink: typeof import("node:fs/promises").unlink;
 };
-type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "unlinkSync" | "writeSync">;
+type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "writeSync">;
 export declare function assertDestinationHardlinkPolicy(fsModule: AsyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): Promise<void>;
 export declare function assertDestinationHardlinkPolicySync(fsModule: SyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): void;
 export declare function copyFallbackReplace(params: {

package/dist/root-impl.js

@@ -798,7 +798,6 @@ async function mkdirPathInRoot(root, params) {
     const prepared = policy && resolved.relativePosix !== ""
         ? await preparePinnedWriteMutationAdmission({
             rootReal: resolved.rootReal,
-            rootWithSep: ensureTrailingSep(resolved.rootReal),
             rootIdentity: root.rootIdentity,
             resolvedTargetPath: resolved.resolved,
             originalPath: params.relativePath,
@@ -1045,10 +1044,8 @@ async function resolvePinnedRootPathInRoot(root, params) {
             throw err;
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
-    const rootWithSep = ensureTrailingSep(resolved.rootCanonicalPath);
     return {
         rootReal: resolved.rootCanonicalPath,
-        rootWithSep,
         canonicalPath: resolved.canonicalPath,
     };
 }

package/dist/root-observed-path.d.ts

@@ -1,7 +1,6 @@
 import { type RootPathObservationKind, type RootPathObservationReceipt } from "./root-path.js";
 import { type RootContext } from "./root-context.js";
 export type PinnedObservedPath = {
-    rootReal: string;
     resolved: string;
     receipt?: RootPathObservationReceipt;
 };

package/dist/root-observed-path.js

@@ -63,7 +63,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
         // A receipt is emitted only for the straight traversal whose lexical and
         // canonical cursors stayed identical and inside the checked boundary.
         return {
-            rootReal: resolved.rootCanonicalPath,
             resolved: resolved.canonicalPath,
             receipt: observed.receipt,
         };
@@ -71,7 +70,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
     const relativeResolved = path.relative(resolved.rootCanonicalPath, resolved.canonicalPath);
     if (relativeResolved === "" || relativeResolved === ".") {
         return {
-            rootReal: resolved.rootCanonicalPath,
             resolved: resolved.canonicalPath,
         };
     }
@@ -87,7 +85,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
     if (!admittedCanonicalPath)
         throw outsideWorkspaceError();
     return {
-        rootReal: resolved.rootCanonicalPath,
         resolved: admittedCanonicalPath.path,
     };
 }

package/dist/root-path-observation.d.ts

@@ -7,14 +7,11 @@ export type RootPathObservationKind = "stat" | "directory";
 export type RootPathDirectoryObservationGuard = DirectoryObservationGuard | NativeDirectoryObservationGuard;
 export type RootPathTargetObservation = StatObservationReceipt | NativeDirectoryObservationGuard;
 /** An exact receipt owned by one stat/list operation. Never cache it. */
-export type RootPathObservationReceipt = {
-    kind: RootPathObservationKind;
-    rootGuard: DirectoryObservationGuard;
+export type RootPathObservationReceipt = Pick<RootPathObservationRequest & {
     directoryGuard: RootPathDirectoryObservationGuard;
-    directoryObserver?: NativeDirectoryObservationBackend;
     targetPath: string;
     target: RootPathTargetObservation;
-};
+}, "kind" | "rootGuard" | "directoryGuard" | "directoryObserver" | "targetPath" | "target">;
 /** A failed initial target lookup must not discard its already admitted parent. */
 export type RootPathParentObservationReceipt = Omit<RootPathObservationReceipt, "kind" | "target"> & {
     kind: "stat-parent";
@@ -24,16 +21,12 @@ export type RootPathObservationRequest = {
     rootGuard: DirectoryObservationGuard;
     directoryObserver?: NativeDirectoryObservationBackend;
 };
-export type RootPathTraversalObservation = {
+export type RootPathTraversalObservation = Omit<Partial<RootPathObservationReceipt> & {
     enabled: boolean;
     request: RootPathObservationRequest;
     targetIndex: number;
     directoryIndex: number;
-    directoryGuard?: RootPathDirectoryObservationGuard;
-    directoryObserver?: NativeDirectoryObservationBackend;
-    targetPath?: string;
-    target?: RootPathTargetObservation;
-};
+}, "kind" | "rootGuard">;
 export type RootPathObservedTraversalEntry = StatObservationReceipt | {
     stat: fs.Stats | BigIntStats;
     identity?: undefined;

package/dist/root-path.js

@@ -214,8 +214,8 @@ function finalizeLexicalResolution(context, kind) {
         rootPath: context.rootPath,
         rootCanonicalPath: context.rootCanonicalPath,
         relativePath: relativeInsideRoot(context.rootCanonicalPath, context.state.canonicalCursor),
-        exists: kind.exists,
-        kind: kind.kind,
+        exists: kind !== "missing",
+        kind,
     };
 }
 function applyResolvedSymlinkHop(context, linkCanonical) {
@@ -374,12 +374,9 @@ function traverseRootPath(params, { mode = "native", observation: observationOut
     const completeObservation = observation?.enabled === true && observation.directoryGuard !== undefined &&
         observation.targetPath === state.canonicalCursor && observation.target !== undefined;
     const kind = completeObservation
-        ? {
-            exists: true,
-            kind: isNativeDirectoryObservationGuard(observation.target)
-                ? "directory"
-                : toResolvedKind(observation.target.stat),
-        }
+        ? isNativeDirectoryObservationGuard(observation.target)
+            ? "directory"
+            : toResolvedKind(observation.target.stat)
         : getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
     if (completeObservation && observationOutput) {
         observationOutput.receipt = {
@@ -399,11 +396,11 @@ function getPathKindSync(absolutePath, preserveFinalSymlink) {
         const stat = preserveFinalSymlink
             ? fs.lstatSync(operationPath)
             : fs.statSync(operationPath);
-        return { exists: true, kind: toResolvedKind(stat) };
+        return toResolvedKind(stat);
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
-            return { exists: false, kind: "missing" };
+            return "missing";
         }
         throw error;
     }

package/dist/root-write-admission.js

@@ -201,7 +201,6 @@ export async function resolveGuardedWriteTargetInRoot(root, params) {
     const relativeParent = path.relative(resolvedPath.rootReal, path.dirname(resolvedPath.resolved));
     const prepared = await preparePinnedWriteMutationAdmission({
         rootReal: resolvedPath.rootReal,
-        rootWithSep: resolvedPath.rootWithSep,
         rootIdentity: root.rootIdentity,
         resolvedTargetPath: resolvedPath.resolved,
         originalPath: params.relativePath,
@@ -288,7 +287,6 @@ export async function resolvePinnedWriteTargetInRoot(root, relativePath, request
     if (policy) {
         ({ relativeParentPath, mutationAdmission } = await preparePinnedWriteMutationAdmission({
             rootReal,
-            rootWithSep,
             rootIdentity: root.rootIdentity,
             resolvedTargetPath: resolved,
             originalPath: relativePath,

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

@@ -7,5 +7,6 @@ export declare function assertNoDriveRelativePathSegments(value: string, label:
 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 normalizeSafePathSegment(value: string): string;
 export declare function sanitizeSafePathSegment(value: string): string | undefined;
 export declare function assertSafePathPrefix(prefix: string, options?: SafePathSegmentOptions): string;

package/dist/safe-path-segment.js

@@ -1,3 +1,4 @@
+import { isWindowsReservedDeviceName } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 const SAFE_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
 const SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
@@ -34,6 +35,8 @@ export function isSafePathSegment(segment, options = {}) {
         !segment.includes("/") &&
         !segment.includes("\\") &&
         !segment.includes("\0") &&
+        // Segments are portable identifiers: CON.json and CON.<pid>.tmp name devices on Windows.
+        !isWindowsReservedDeviceName(segment) &&
         (options.allowDotPrefix === true || !segment.startsWith(".")) &&
         (options.allowDotPrefix === true
             ? SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN.test(segment)
@@ -47,13 +50,16 @@ export function assertSafePathSegment(segment, options = {}) {
     }
     return segment;
 }
-export function sanitizeSafePathSegment(value) {
+export function normalizeSafePathSegment(value) {
     const sanitized = value
         .trim()
         .replace(/[\\/]+/g, "-")
         .replace(/\0/g, "")
         .replace(/[^A-Za-z0-9._-]+/g, "-");
-    const trimmed = trimHyphenEdges(sanitized);
+    return trimHyphenEdges(sanitized);
+}
+export function sanitizeSafePathSegment(value) {
+    const trimmed = normalizeSafePathSegment(value);
     return isSafePathSegment(trimmed, { allowDotPrefix: true }) ? trimmed : undefined;
 }
 export function assertSafePathPrefix(prefix, options = {}) {

package/dist/secure-file.js

@@ -202,7 +202,8 @@ function inspectOpenedPermissions(stat, platform) {
         groupReadable: isGroupReadable(bits),
     };
 }
-async function assertSecurePermissions(options, stat, realPath, identity, fd) {
+async function assertSecurePermissions(options, opened, fd) {
+    const { pathStat: stat, realPath, identity } = opened;
     if (options.permissions?.allowInsecure) {
         return undefined;
     }
@@ -282,7 +283,7 @@ export async function readSecureFile(options) {
     const opened = await openSecureHandle(options, maxBytes);
     try {
         assertTrustedDirs(options, opened.realPath);
-        const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath, opened.identity, opened.handle.fd);
+        const permissions = await assertSecurePermissions(options, opened, opened.handle.fd);
         const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs, maxBytes);
         const finalIdentity = inspectFileIdentitySync(() => fsSync.fstatSync(opened.handle.fd, { bigint: true }), opened.identity);
         if (!finalIdentity.isFile()) {

package/dist/sidecar-lock.js

@@ -1,6 +1,6 @@
 import fsSync from "node:fs";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { removeSidecarLockIfUnchanged, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
 import { acquireSidecarLock } from "./sidecar-lock-acquire.js";
 import { createHeldSidecarLockHandle, stopSidecarLockMonitoring } from "./sidecar-lock-handle.js";
@@ -61,7 +61,9 @@ function snapshotMatchesSync(lockPath, observed) {
             (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0);
         fd = fsSync.openSync(lockPath, openFlags);
         const openedStat = fsSync.fstatSync(fd);
-        if (!openedStat.isFile()) {
+        // Token-owned files can have different descriptor/path identities on VirtioFS.
+        // Require a known descriptor identity without rejecting that supported drift.
+        if (!openedStat.isFile() || !sameFileIdentityForCleanup(openedStat, openedStat)) {
             return false;
         }
         if (observed.raw !== undefined && openedStat.size !== Buffer.byteLength(observed.raw)) {
@@ -69,7 +71,7 @@ function snapshotMatchesSync(lockPath, observed) {
         }
         const raw = fsSync.readFileSync(fd, "utf8");
         const afterStat = fsSync.lstatSync(lockPath);
-        if (!afterStat.isFile() || !sameFileIdentity(beforeStat, afterStat)) {
+        if (!afterStat.isFile() || !sameFileIdentityForCleanup(beforeStat, afterStat)) {
             return false;
         }
         return sidecarLockSnapshotMatches({ raw, payload: null, stat: afterStat }, observed);

package/dist/staged-symlink-types.d.ts

@@ -0,0 +1,49 @@
+import type { StagedFileReceipt } from "./staged-file-types.js";
+/** Caller-captured admission evidence, never a same-target ownership heuristic. */
+export type StagedSymlinkExpected = Readonly<{
+    dev: bigint;
+    ino: bigint;
+    uid: number;
+    gid: number;
+    ctimeNs: bigint;
+    target: string;
+}>;
+export type StagedSymlinkReceipt = StagedFileReceipt & Readonly<{
+    target: string;
+}>;
+export type PublishedSymlinkReceipt = Readonly<{
+    status: "published";
+    staged: StagedSymlinkReceipt;
+    basename: string;
+    overwrite: false;
+}>;
+export type StagedSymlinkPublication = Readonly<{
+    status: "not-published";
+}> | PublishedSymlinkReceipt | Readonly<{
+    status: "indeterminate";
+    basename: string;
+    overwrite: false;
+}>;
+export type StagedSymlinkRemoval = "removed" | "name-absent" | "preserved";
+export type StagedSymlinkCleanupReceipt = Readonly<{
+    temporaryBasename: string;
+    publication: StagedSymlinkPublication;
+    status: StagedSymlinkRemoval | "failed" | "not-needed";
+    resources: "closed" | "close-failed";
+}>;
+export type StagedSymlinkFailureDetails = Readonly<{
+    phase: "prepare" | "publish" | "remove-published" | "cleanup";
+    publication: StagedSymlinkPublication;
+    cleanup?: StagedSymlinkCleanupReceipt;
+}>;
+export interface StagedSymlink extends AsyncDisposable {
+    readonly receipt: StagedSymlinkReceipt;
+    assertCurrent(): Promise<void>;
+    publish(basename: string): Promise<PublishedSymlinkReceipt>;
+    /** Check the published name against the still-retained original symlink. */
+    assertPublished(): Promise<void>;
+    /** Explicit recovery only. Never removes an observed foreign replacement. */
+    removePublished(): Promise<StagedSymlinkRemoval>;
+    /** Closes the owner; only an unattempted, still-owned stage is removed. */
+    cleanup(): Promise<StagedSymlinkCleanupReceipt>;
+}

package/dist/staged-symlink-types.js

@@ -0,0 +1 @@
+export {};

package/dist/symlink-parents.js

@@ -3,24 +3,46 @@ import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { hasNodeErrorCode, isPathRelativeEscape } from "./path.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function outsideRootError(params, root) {
+    return new Error(`${params.messagePrefix ?? "Path"} must stay under ${root}.`);
+}
+function pathSegments(value) {
+    return value.split(process.platform === "win32" ? /[/\\]+/ : /\/+/)
+        .filter((segment) => segment.length > 0 && segment !== ".");
+}
+function rawTargetSegments(root, targetPath) {
+    // Resolve only the drive/root or cwd, never the caller's dotdot segments.
+    const targetRoot = path.parse(targetPath).root;
+    const base = resolvePathPreservingWindowsRoot(targetRoot || ".");
+    const absoluteTarget = `${base}${path.sep}${targetPath.slice(targetRoot.length)}`;
+    const rootSegments = pathSegments(root);
+    const targetSegments = pathSegments(absoluteTarget);
+    const fold = (segment) => process.platform === "win32" ? segment.toLowerCase() : segment;
+    if (rootSegments.some((segment, index) => fold(segment) !== fold(targetSegments[index] ?? ""))) {
+        return undefined;
+    }
+    return targetSegments.slice(rootSegments.length);
+}
 function resolvePathWalk(params) {
     const rawRootDir = params.rootDir;
     assertNoWindowsPathAlias(rawRootDir, "filesystem", "root dir uses a Windows filesystem namespace alias");
     const rawTargetPath = params.targetPath;
     assertNoWindowsPathAlias(rawTargetPath, "filesystem", "target path uses a Windows filesystem namespace alias");
     const root = resolvePathPreservingWindowsRoot(rawRootDir);
-    const target = resolvePathPreservingWindowsRoot(rawTargetPath);
-    const relative = path.relative(root, target);
+    const lexicalTarget = resolvePathPreservingWindowsRoot(rawTargetPath);
+    const relative = path.relative(root, lexicalTarget);
     if (isPathRelativeEscape(relative)) {
         if (params.allowOutsideRoot) {
             return null;
         }
-        throw new Error(`${params.messagePrefix ?? "Path"} must stay under ${root}.`);
+        throw outsideRootError(params, root);
     }
-    return {
-        root,
-        segments: relative && relative !== "." ? relative.split(path.sep).filter(Boolean) : [],
-    };
+    const segments = rawTargetSegments(root, rawTargetPath);
+    // A spelling outside the root must not fall back to a normalized walk that
+    // could erase a symlink before the filesystem receives the original path.
+    if (!segments)
+        throw outsideRootError(params, root);
+    return { root, segments };
 }
 function formatUnsafePath(params, current) {
     return `${params.messagePrefix ?? "Path"} must not traverse symlinked directory: ${current}`;
@@ -28,18 +50,39 @@ function formatUnsafePath(params, current) {
 export async function assertNoSymlinkParents(params) {
     assertNoSymlinkParentsSync(params);
 }
+function isFilesystemRoot(root) {
+    return root === path.parse(root).root;
+}
 export function assertNoSymlinkParentsSync(params) {
     const walk = resolvePathWalk(params);
     if (!walk) {
         return;
     }
     let current = walk.root;
+    // `..` may only undo a real directory this walk already lstat'd.
+    const walked = [];
     for (const [index, segment] of walk.segments.entries()) {
+        if (segment === "..") {
+            const top = walked[walked.length - 1];
+            if (top?.kind === "dir") {
+                walked.pop();
+                current = walked[walked.length - 1]?.path ?? walk.root;
+                continue;
+            }
+            if (top?.kind === "symlink") {
+                throw new Error(formatUnsafePath(params, top.path));
+            }
+            if (!isFilesystemRoot(walk.root)) {
+                throw outsideRootError(params, walk.root);
+            }
+            continue;
+        }
         current = path.join(current, segment);
         try {
             const stat = fsSync.lstatSync(current);
             if (stat.isSymbolicLink()) {
                 if (params.allowRootChildSymlink && path.dirname(current) === walk.root) {
+                    walked.push({ path: current, kind: "symlink" });
                     continue;
                 }
                 throw new Error(formatUnsafePath(params, current));
@@ -47,9 +90,17 @@ export function assertNoSymlinkParentsSync(params) {
             if ((params.requireDirectories || index < walk.segments.length - 1) && !stat.isDirectory()) {
                 throw new FsSafeError("not-file", `${params.messagePrefix ?? "Path"} must traverse directories: ${current}`);
             }
+            if (stat.isDirectory()) {
+                walked.push({ path: current, kind: "dir" });
+            }
         }
         catch (err) {
             if (hasNodeErrorCode(err, "ENOENT") && params.allowMissing !== false) {
+                // Win32 can cancel a nonexistent component before filesystem lookup.
+                // Returning early would leave later, reachable symlinks unchecked.
+                if (process.platform === "win32" && walk.segments.slice(index + 1).includes("..")) {
+                    throw new FsSafeError("invalid-path", `${params.messagePrefix ?? "Path"} must not cancel a missing directory: ${current}`);
+                }
                 return;
             }
             throw err;

package/dist/temp-target.js

@@ -4,7 +4,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { suffixWindowsReservedDeviceName } from "./filename.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
-import { assertSafePathSegment, sanitizeSafePathSegment, trimHyphenEdges } from "./safe-path-segment.js";
+import { assertSafePathSegment, normalizeSafePathSegment, sanitizeSafePathSegment, trimHyphenEdges, } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { hasNodeErrorCode } from "./path.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
@@ -60,7 +60,9 @@ function sanitizeExtension(extension) {
     return token ? `.${token}` : "";
 }
 export function sanitizeTempFileName(fileName) {
-    return suffixWindowsReservedDeviceName(sanitizeSafePathSegment(path.basename(fileName)) ?? "download.bin");
+    // Suffix reserved stems before admission so CON.txt stays CON_.txt.
+    const suffixed = suffixWindowsReservedDeviceName(normalizeSafePathSegment(path.basename(fileName)));
+    return sanitizeSafePathSegment(suffixed) ?? "download.bin";
 }
 export function buildRandomTempFilePath(params) {
     const rootDir = resolveTempRoot(params.rootDir);

package/dist/temp-workspace-owner.js

@@ -14,13 +14,6 @@ function isNativeCleanupBinding(binding) {
         typeof binding.removeOwnedTreeSync === "function" &&
         typeof binding.ownedTreeRemovalAvailable === "function";
 }
-function nativeRemovalError(result) {
-    if (!result.errorCode)
-        return undefined;
-    return Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), {
-        code: result.errorCode,
-    });
-}
 export class TempWorkspaceCleanupCapability {
     binding;
     parent;
@@ -309,8 +302,10 @@ export class TempWorkspaceCleanupOwner {
         this.#capability.assertCurrent();
     }
     #mapRemoval(result) {
-        const error = nativeRemovalError(result);
-        if (error) {
+        if (result.errorCode) {
+            const error = Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), {
+                code: result.errorCode,
+            });
             if (error.code === "path-mismatch")
                 return "indeterminate";
             throw error;

package/dist/text-atomic.d.ts

@@ -1,4 +1,5 @@
-export type WriteTextAtomicOptions = {
+import { type ReplaceFileAtomicOptions } from "./replace-file.js";
+export type WriteTextAtomicOptions = Pick<ReplaceFileAtomicOptions, "beforeRename" | "tempPrefix"> & {
     mode?: number;
     dirMode?: number;
     trailingNewline?: boolean;

package/dist/text-atomic.js

@@ -12,5 +12,7 @@ export async function writeTextAtomic(filePath, content, options) {
         copyFallbackOnPermissionError: true,
         syncTempFile: durable,
         syncParentDir: durable,
+        beforeRename: options?.beforeRename,
+        tempPrefix: options?.tempPrefix,
     });
 }

package/dist/trash.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { assertSyncDirectoryGuard, createSyncDirectoryGuard } from "./directory-guard.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { guardedRenameSync, guardedRmSync } from "./guarded-mutation.js";
 import { realpathSync } from "./realpath.js";
@@ -72,6 +73,22 @@ function resolveTrashTargetPath(targetPath) {
     assertNoTrashPathAlias(resolvedPath, "target path");
     return { path: resolvedPath, resolved: true };
 }
+function resolveTrashEntryParent(lexicalTarget, targetPath) {
+    const lexicalParent = path.dirname(lexicalTarget);
+    assertNoTrashPathAlias(lexicalParent, "target path");
+    let realParent;
+    try {
+        // The renamed name lives in this parent. rename follows intermediate
+        // symlinks, so a lexical parent inside an allowed root is not enough.
+        realParent = realpathSync.native(lexicalParent);
+    }
+    catch {
+        throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
+    }
+    const resolvedParent = path.resolve(realParent);
+    assertNoTrashPathAlias(resolvedParent, "target path");
+    return resolvedParent;
+}
 function assertAllowedTrashTarget(targetPath, allowedRoots) {
     assertNoTrashPathAlias(targetPath, "target path");
     const lexicalTarget = path.resolve(targetPath);
@@ -79,11 +96,19 @@ function assertAllowedTrashTarget(targetPath, allowedRoots) {
     const stat = fs.lstatSync(lexicalTarget);
     const resolvedTarget = resolveTrashTargetPath(targetPath);
     const resolvedTargetPath = resolvedTarget.path;
-    const isAllowed = resolveAllowedTrashRoots(allowedRoots).some((root) => resolvedTargetPath !== root && isSameOrChildPath(resolvedTargetPath, root));
+    const parent = createSyncDirectoryGuard(path.dirname(lexicalTarget));
+    // Admit the directory entry only when its parent really stays inside an
+    // allowed root. Do not admit it because the symlink target is inside.
+    const resolvedParent = resolveTrashEntryParent(lexicalTarget, targetPath);
+    const isAllowed = resolveAllowedTrashRoots(allowedRoots).some((root) => isSameOrChildPath(resolvedParent, root));
     if (!isAllowed) {
         throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
     }
+    // Sync and native realpath can use different Windows short-name spellings.
+    // Recheck the retained guard around native containment instead of comparing them.
+    assertSyncDirectoryGuard(parent);
     return {
+        parent,
         path: lexicalTarget,
         realPath: resolvedTargetPath,
         realPathResolved: resolvedTarget.resolved,
@@ -91,6 +116,7 @@ function assertAllowedTrashTarget(targetPath, allowedRoots) {
     };
 }
 function assertTrashTargetGuard(guard) {
+    assertSyncDirectoryGuard(guard.parent);
     const stat = fs.lstatSync(guard.path);
     if (!sameFileIdentity(stat, guard.stat)) {
         throw new Error(`Refusing to trash path after it changed: ${guard.path}`);

package/dist/walk.d.ts

@@ -20,12 +20,9 @@ export type AsyncWalkDirectoryOptions = Omit<WalkDirectoryOptions, "include" | "
     include?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
     descend?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
 };
-export type WalkDirectoryFailure = {
-    path: string;
-    relativePath: string;
-    depth: number;
+export type WalkDirectoryFailure = Pick<WalkDirectoryEntry & {
     error: unknown;
-};
+}, "path" | "relativePath" | "depth" | "error">;
 export type WalkDirectoryResult = {
     entries: WalkDirectoryEntry[];
     scannedEntryCount: number;

package/dist/windows-owner.d.ts

@@ -9,7 +9,6 @@ export type WindowsOwnerSummary = Omit<PermissionFailureFields & {
     daclPresent?: boolean;
     aces?: WindowsOwnerAce[];
     aclError?: string;
-    remote?: boolean;
     trusted?: boolean;
 }, never>;
 export type WindowsOwnerAce = {

package/dist/windows-owner.js

@@ -87,7 +87,6 @@ export async function inspectWindowsOwner(params) {
             sid: ownerSid,
             currentUserSid,
             ...parseWindowsAclFacts(parsed),
-            remote,
             trusted: !remote && (ownerSid === currentUserSid || TRUSTED_OWNER_SIDS.has(ownerSid)),
         };
     }

package/dist/windows-security-bridge.cs

@@ -312,6 +312,10 @@ public static partial class FsSafeWindowsBridge {
       }
     }
   }
+  static object InspectPath(string path) {
+    // Raw reporting retains ACL facts when locality is unknown; admission remains strict.
+    using(var handle=Open(path,0x00020080,false)) return Security(handle,false);
+  }
   public static object Execute(string operation,string path) {
     try {
       object result;
@@ -323,10 +327,8 @@ public static partial class FsSafeWindowsBridge {
           Require(!handle.IsInvalid,"EBADF","inherited file handle is unavailable");
           result=Row("identity",Identity(handle),"security",Security(handle));
         }
-      } else if(operation=="path") {
-        // Raw reporting retains ACL facts when locality is unknown; admission remains strict.
-        using(var handle=Open(path,0x00020080,false)) result=Security(handle,false);
-      } else throw new Failure("EINVAL","unknown Windows security operation");
+      } else if(operation=="path") result=InspectPath(path);
+      else throw new Failure("EINVAL","unknown Windows security operation");
       return Row("ok",true,"result",result);
     } catch(Failure error) { return Row("ok",false,"code",error.Code,"message",error.Message); }
       catch(Exception) { return Row("ok",false,"code","EIO","message","Windows security descriptor processing failed"); }