@openclaw/fs-safe 0.20.0 → 0.21.0

package/dist/root-directory-list.d.ts

@@ -2,6 +2,7 @@ import type { BigIntStats, Stats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type RootContext } from "./root-context.js";
 import type { RootPathDirectoryObservationGuard, RootPathObservationReceipt, RootPathParentObservationReceipt } from "./root-path.js";
+import { type ExactStatIdentity } from "./stat-observation.js";
 import type { DirEntry, PathStat } from "./types.js";
 export declare function pathStatFromStats(stat: Stats | BigIntStats): PathStat;
 export type RootDirectoryObservationGuard = AsyncDirectoryGuard<BigIntStats>;
@@ -21,6 +22,7 @@ export type RootDirectoryListing = {
     next(): Promise<{
         kind: "entry";
         entry: DirEntry;
+        identity?: ExactStatIdentity;
     } | {
         kind: "limit";
         name: string;
@@ -33,6 +35,10 @@ export type RootDirectoryListingOptions = {
     snapshot: boolean;
     maxNames?: number;
     metadataBatchSize?: number;
+    /** Internal exact metadata lane, supported by streaming filesystem order. */
+    exactIdentity?: boolean;
+    /** Internal owner receives cleanup failures, including acquisition rollback. */
+    onCleanupFailure?: (error: unknown) => void;
     admitEntry(): boolean;
 };
-export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
+export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions, receipt?: RootPathObservationReceipt): Promise<RootDirectoryListing>;

package/dist/root-directory-list.js

@@ -11,6 +11,7 @@ import { errorCauseOptions, rootPathChangedError } from "./root-errors.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { realpathSync } from "./realpath.js";
+import { inspectStatObservationSync } from "./stat-observation.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const METADATA_BATCH_SIZE = 32;
 export function pathStatFromStats(stat) {
@@ -173,14 +174,7 @@ function normalizeInitialDirectoryError(error) {
 export async function listDirectoryPath(root, directory, withFileTypes, receipt) {
     let guard;
     if (receipt) {
-        if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
-            receipt.directoryGuard.dir !== directory ||
-            receipt.target !== receipt.directoryGuard ||
-            (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
-                !receipt.directoryGuard.stat.isDirectory())) {
-            throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
-        }
-        guard = receipt.directoryGuard;
+        guard = directoryGuardFromReceipt(directory, receipt);
     }
     else {
         try {
@@ -192,6 +186,16 @@ export async function listDirectoryPath(root, directory, withFileTypes, receipt)
     }
     return await listGuardedDirectoryPath(root, guard, withFileTypes, receipt);
 }
+function directoryGuardFromReceipt(directory, receipt) {
+    if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
+        receipt.directoryGuard.dir !== directory ||
+        receipt.target !== receipt.directoryGuard ||
+        (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
+            !receipt.directoryGuard.stat.isDirectory())) {
+        throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
+    }
+    return receipt.directoryGuard;
+}
 async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
     let entries;
     try {
@@ -221,19 +225,30 @@ async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
         await assertRootDirectoryObservationGuard(root, guard);
     return entries;
 }
-export async function openRootDirectoryListing(root, directory, options) {
-    const admitted = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
-        throw normalizeDirectoryError(error);
-    });
-    // Retain exact admission identities; metadata rechecks can use numeric Stats
-    // only when every identity component is losslessly representable.
-    const guard = extendDirectoryObservationGuard({
-        stat: admitted.stat,
-        identity: { dev: admitted.stat.dev, ino: admitted.stat.ino },
-    }, admitted.dir, admitted.realPath);
+export async function openRootDirectoryListing(root, directory, options, receipt) {
+    if (options.exactIdentity && options.order !== "filesystem")
+        throw new TypeError("exact entry identities require filesystem order");
+    let guard;
+    if (receipt) {
+        guard = directoryGuardFromReceipt(directory, receipt);
+    }
+    else {
+        const admitted = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
+            throw normalizeDirectoryError(error);
+        });
+        // Retain exact admission identities; metadata rechecks can use numeric Stats
+        // only when every identity component is losslessly representable.
+        guard = extendDirectoryObservationGuard({
+            stat: admitted.stat,
+            identity: { dev: admitted.stat.dev, ino: admitted.stat.ino },
+        }, admitted.dir, admitted.realPath);
+    }
     const assertCurrent = async () => {
         options.signal?.throwIfAborted();
-        await assertRootDirectoryObservationGuard(root, guard);
+        if (receipt)
+            assertRootPathObservationReceiptCurrent(root, receipt);
+        else
+            await assertRootDirectoryObservationGuard(root, guard);
         options.signal?.throwIfAborted();
     };
     let handle;
@@ -248,7 +263,13 @@ export async function openRootDirectoryListing(root, directory, options) {
     const close = async () => {
         const owned = handle;
         handle = undefined;
-        await owned?.close();
+        try {
+            await owned?.close();
+        }
+        catch (error) {
+            options.onCleanupFailure?.(error);
+            throw error;
+        }
     };
     try {
         await assertCurrent();
@@ -257,7 +278,7 @@ export async function openRootDirectoryListing(root, directory, options) {
             handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
         }
         else if (options.snapshot) {
-            snapshot = await listGuardedDirectoryPath(root, guard, true);
+            snapshot = await listGuardedDirectoryPath(root, guard, true, receipt);
         }
         else if (options.maxNames !== undefined) {
             names = [];
@@ -369,9 +390,13 @@ export async function openRootDirectoryListing(root, directory, options) {
                 if (!options.admitEntry())
                     return { kind: "limit", name };
                 // The stream's post-read fence is also the pre-stat fence in this owned operation.
-                const stat = fsSync.lstatSync(path.join(guard.realPath, name));
+                const pathname = path.join(guard.realPath, name);
+                const observed = options.exactIdentity ? inspectStatObservationSync(bigint => bigint
+                    ? fsSync.lstatSync(pathname, { bigint: true }) : fsSync.lstatSync(pathname)) : undefined;
+                const stat = observed?.stat ?? fsSync.lstatSync(pathname);
                 await assertCurrent();
-                return { kind: "entry", entry: { name, ...pathStatFromStats(stat) } };
+                const entry = { name, ...pathStatFromStats(stat) };
+                return observed ? { kind: "entry", entry, identity: observed.identity } : { kind: "entry", entry };
             }
             catch (error) {
                 throw normalizeDirectoryError(error);

package/dist/root-handle-context.d.ts

@@ -0,0 +1,4 @@
+import type { RootContext } from "./root-context.js";
+/** Internal registration; never reconstruct authority from public pathname fields. */
+export declare function registerRootHandleContext(handle: object, context: RootContext): void;
+export declare function rootHandleContext(handle: object): RootContext;

package/dist/root-handle-context.js

@@ -0,0 +1,12 @@
+import { FsSafeError } from "./errors.js";
+const contexts = new WeakMap();
+/** Internal registration; never reconstruct authority from public pathname fields. */
+export function registerRootHandleContext(handle, context) {
+    contexts.set(handle, context);
+}
+export function rootHandleContext(handle) {
+    const context = contexts.get(handle);
+    if (!context)
+        throw new FsSafeError("invalid-path", "watch requires a genuine fs-safe Root");
+    return context;
+}

package/dist/root-impl.d.ts

@@ -5,7 +5,7 @@ import { type ReadResult } from "./read-opened-file.js";
 import { type RootEntriesOptions } from "./root-entries.js";
 import { type RootContext } from "./root-context.js";
 import type { DirEntry, PathStat } from "./types.js";
-import { type RootWalkEntry, type RootWalkOptions } from "./root-walk.js";
+import { type RootWalkEntry, type RootWalkOptions, type RootWalkSymlinkPolicy } from "./root-walk.js";
 import { type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions } from "./root-options.js";
 export { DEFAULT_ROOT_MAX_BYTES } from "./root-options.js";
 export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
@@ -54,7 +54,7 @@ export interface Root {
     }): Promise<DirEntry[]>;
     entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
     move(fromRelative: string, toRelative: string, options?: RootMoveOptions): Promise<void>;
-    walk(relativePath: string, options: RootWalkOptions): AsyncIterableIterator<RootWalkEntry>;
+    walk<Policy extends RootWalkSymlinkPolicy>(relativePath: string, options: RootWalkOptions<Policy>): AsyncIterableIterator<RootWalkEntry<Policy>>;
 }
 export declare class RootHandle implements Root {
     private readonly context;
@@ -97,7 +97,7 @@ export declare class RootHandle implements Root {
     }): Promise<DirEntry[]>;
     move(fromRelative: string, toRelative: string, options?: RootMoveOptions): Promise<void>;
     entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
-    walk(relativePath: string, options: RootWalkOptions): AsyncIterableIterator<RootWalkEntry>;
+    walk<Policy extends RootWalkSymlinkPolicy>(relativePath: string, options: RootWalkOptions<Policy>): AsyncIterableIterator<RootWalkEntry<Policy>>;
 }
 export declare function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 export declare function rootFromDirectoryGuard(guard: {

package/dist/root-impl.js

@@ -51,6 +51,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { randomUUID } from "node:crypto";
+import { registerRootHandleContext } from "./root-handle-context.js";
 import fsSync, { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -85,7 +86,7 @@ import { listDirectoryPath, openRootDirectoryListing } from "./root-directory-li
 import { statResolvedPathInRoot } from "./root-path-stat.js";
 import { entriesInRoot } from "./root-entries.js";
 import { assertMoveMutationAllowed } from "./root-move-preflight.js";
-import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
+import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, createRootObservationGuard, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
 import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
@@ -199,6 +200,7 @@ export class RootHandle {
         this.rootWithSep = context.rootWithSep;
         this.defaults = defaults;
         registerFileLockSyncRootAdapter(this, context, defaults);
+        registerRootHandleContext(this, context);
     }
     mutationOptions(options) {
         return {
@@ -409,9 +411,13 @@ export class RootHandle {
         assertValidRootRelativePath(relativePath);
         return walkRoot({
             rootReal: this.context.rootReal,
+            observeRoot: () => createRootObservationGuard(this.context),
             stat: relative => this.stat(relative),
-            list: async (relative, listingOptions) => {
+            list: async (relative, listingOptions, receipt) => {
                 validatePinnedRelativePath(relative);
+                if (receipt) {
+                    return await openRootDirectoryListing(this.context, receipt.targetPath, listingOptions, receipt);
+                }
                 const resolved = await resolvePinnedPathInRoot(this.context, { relativePath: relative, allowRoot: true });
                 return await openRootDirectoryListing(this.context, resolved.resolved, listingOptions);
             },

package/dist/root-walk.d.ts

@@ -1,17 +1,21 @@
+import type { DirectoryObservationGuard } from "./directory-guard.js";
+import { type RootPathObservationReceipt } from "./root-path.js";
 import type { RootDirectoryListing, RootDirectoryListingOptions } from "./root-directory-list.js";
 import type { PathStat } from "./types.js";
-export type RootWalkSymlinkPolicy = "skip" | "follow-within-root";
+export type RootWalkSymlinkPolicy = "skip" | "follow-within-root" | "include";
+type LegacyRootWalkSymlinkPolicy = Exclude<RootWalkSymlinkPolicy, "include">;
 export type RootWalkLimitBehavior = "truncate" | "throw";
 export type RootWalkDirectoryErrorBehavior = "throw" | "skip-and-report";
 export type RootWalkEntryFilterResult = "include" | "skip" | "skip-subtree";
-export type RootWalkDataEntryKind = "file" | "directory" | "other";
-export type RootWalkEntryKind = RootWalkDataEntryKind | "directory-error" | "truncated";
-export type RootWalkDataEntry = {
+export type RootWalkDataEntryKind<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = "file" | "directory" | "other" | ("include" extends Policy ? "symlink" : never);
+export type RootWalkEntryKind<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = RootWalkDataEntryKind<Policy> | "directory-error" | "truncated";
+type WalkEntryOfKind<Kind extends RootWalkDataEntryKind<RootWalkSymlinkPolicy>> = {
     relativePath: string;
-    kind: RootWalkDataEntryKind;
+    kind: Kind;
     size: number;
 };
-export type RootWalkEntry = RootWalkDataEntry | {
+export type RootWalkDataEntry<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = WalkEntryOfKind<RootWalkDataEntryKind> | ("include" extends Policy ? WalkEntryOfKind<"symlink"> : never);
+export type RootWalkEntry<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = RootWalkDataEntry<Policy> | {
     relativePath: string;
     kind: "truncated";
     size: 0;
@@ -21,21 +25,24 @@ export type RootWalkEntry = RootWalkDataEntry | {
     size: 0;
     error: unknown;
 };
-export type RootWalkEntryFilter = (entry: RootWalkDataEntry) => RootWalkEntryFilterResult | Promise<RootWalkEntryFilterResult>;
-export type RootWalkOptions = {
+export type RootWalkEntryFilter<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = (entry: RootWalkDataEntry<Policy>) => RootWalkEntryFilterResult | Promise<RootWalkEntryFilterResult>;
+export type RootWalkOptions<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = {
     maxDepth?: number;
     maxEntries?: number;
     order?: "sorted" | "filesystem";
-    symlinkPolicy: RootWalkSymlinkPolicy;
+    symlinkPolicy: Policy;
     signal?: AbortSignal;
     limitBehavior?: RootWalkLimitBehavior;
-    entryFilter?: RootWalkEntryFilter;
+    entryFilter?: RootWalkEntryFilter<Policy>;
     onDirectoryError?: RootWalkDirectoryErrorBehavior;
 };
+type AnyRootWalkOptions = RootWalkOptions | RootWalkOptions<"include"> | RootWalkOptions<RootWalkSymlinkPolicy>;
+type AnyRootWalkEntry = RootWalkEntry<RootWalkSymlinkPolicy>;
 type RootWalkCapability = {
     rootReal: string;
+    observeRoot(): Promise<DirectoryObservationGuard | undefined>;
     stat(relativePath: string): Promise<PathStat>;
-    list(relativePath: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
+    list(relativePath: string, options: RootDirectoryListingOptions, receipt?: RootPathObservationReceipt): Promise<RootDirectoryListing>;
 };
-export declare function walkRoot(root: RootWalkCapability, relativePath: string, options: RootWalkOptions): AsyncGenerator<RootWalkEntry>;
+export declare function walkRoot(root: RootWalkCapability, relativePath: string, options: AnyRootWalkOptions): AsyncGenerator<AnyRootWalkEntry>;
 export {};

package/dist/root-walk.js

@@ -1,8 +1,14 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { expandRelativePathWithHome } from "./root-context.js";
-import { resolveRootPath, ROOT_PATH_ALIAS_POLICIES } from "./root-path.js";
+import { resolveRootPath, resolveRootPathWithObservation, ROOT_PATH_ALIAS_POLICIES, RootPathObservationError, } from "./root-path.js";
 import { createSuppressedError } from "./suppressed-error.js";
+function filterEntry(options, entry) {
+    if (entry.kind === "symlink") {
+        return options.symlinkPolicy === "include" ? options.entryFilter?.(entry) ?? "include" : "skip";
+    }
+    return options.entryFilter?.(entry) ?? "include";
+}
 function validateBudget(name, value) {
     if (value === undefined)
         return Number.POSITIVE_INFINITY;
@@ -24,7 +30,7 @@ function limitEntry(relativePath) {
     return { relativePath, kind: "truncated", size: 0 };
 }
 export async function* walkRoot(root, relativePath, options) {
-    if (!["skip", "follow-within-root"].includes(options.symlinkPolicy)) {
+    if (!["skip", "follow-within-root", "include"].includes(options.symlinkPolicy)) {
         throw new TypeError(`invalid root walk symlink policy: ${String(options.symlinkPolicy)}`);
     }
     if (options.order !== undefined && !["sorted", "filesystem"].includes(options.order)) {
@@ -62,24 +68,50 @@ export async function* walkRoot(root, relativePath, options) {
             throw error;
         return { relativePath: directory, kind: "directory-error", size: 0, error };
     };
-    async function* visit(directory, depth) {
+    async function* visit(directory, depth, admittedChildPath) {
         options.signal?.throwIfAborted();
         let listing;
+        let canonicalDirectory;
         try {
             const expandedDirectory = depth === 0 ? await expandRelativePathWithHome(directory) : directory;
-            const skipChildSymlinks = depth > 0 && options.symlinkPolicy === "skip";
-            const resolvedDirectory = await resolveRootPath({
-                absolutePath: path.resolve(root.rootReal, expandedDirectory),
+            const noFollowChildSymlinks = depth > 0 && options.symlinkPolicy !== "follow-within-root";
+            const includeChild = depth > 0 && options.symlinkPolicy === "include";
+            const resolution = {
+                absolutePath: admittedChildPath ?? path.resolve(root.rootReal, expandedDirectory),
                 rootPath: root.rootReal,
                 rootCanonicalPath: root.rootReal,
                 boundaryLabel: "root walk",
-                policy: skipChildSymlinks ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
-            });
-            if (skipChildSymlinks && resolvedDirectory.kind === "symlink")
-                return;
+                policy: noFollowChildSymlinks ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
+            };
+            let receipt;
+            let resolvedDirectory;
+            if (includeChild) {
+                const rootGuard = await root.observeRoot();
+                if (!rootGuard) {
+                    throw new FsSafeError("helper-unavailable", "root walk requires an exact directory observation");
+                }
+                const observed = await resolveRootPathWithObservation({
+                    ...resolution,
+                    rootIdentity: rootGuard.identity,
+                }, { kind: "directory", rootGuard });
+                resolvedDirectory = observed.resolved;
+                receipt = observed.receipt;
+            }
+            else {
+                resolvedDirectory = await resolveRootPath(resolution);
+            }
+            if (noFollowChildSymlinks && resolvedDirectory.kind === "symlink") {
+                if (options.symlinkPolicy === "skip")
+                    return;
+                throw new FsSafeError("path-mismatch", `root walk directory became a symlink: ${directory}`);
+            }
             if (!resolvedDirectory.exists || resolvedDirectory.kind !== "directory") {
                 throw new FsSafeError("not-file", `root walk path is not a directory: ${directory || "."}`);
             }
+            if (includeChild && (!receipt || receipt.directoryGuard.realPath !== resolvedDirectory.canonicalPath)) {
+                throw new FsSafeError("path-mismatch", "root walk directory observation was not retained");
+            }
+            canonicalDirectory = resolvedDirectory.canonicalPath;
             if (visitedDirectories.has(resolvedDirectory.canonicalPath)) {
                 return;
             }
@@ -97,10 +129,10 @@ export async function* walkRoot(root, relativePath, options) {
                 signal: options.signal,
                 snapshot: maxEntries === Number.POSITIVE_INFINITY,
                 admitEntry,
-            });
+            }, receipt);
         }
         catch (error) {
-            yield onDirectoryError(directory, error);
+            yield onDirectoryError(directory, error instanceof RootPathObservationError ? error.error : error);
             return;
         }
         // A thrown undefined still needs to be retained if closing also fails.
@@ -131,10 +163,9 @@ export async function* walkRoot(root, relativePath, options) {
                 const entry = next.entry;
                 let kind = entryKind(entry);
                 let size = entry.size;
-                if (kind === "symlink") {
-                    if (options.symlinkPolicy === "skip") {
-                        continue;
-                    }
+                if (kind === "symlink" && options.symlinkPolicy === "skip")
+                    continue;
+                if (kind === "symlink" && options.symlinkPolicy === "follow-within-root") {
                     const resolved = await resolveRootPath({
                         absolutePath: path.resolve(root.rootReal, child),
                         rootPath: root.rootReal,
@@ -149,7 +180,7 @@ export async function* walkRoot(root, relativePath, options) {
                     size = target.size;
                 }
                 const walkEntry = { relativePath: child, kind, size };
-                let filterResult = options.entryFilter?.(walkEntry) ?? "include";
+                let filterResult = filterEntry(options, walkEntry);
                 if (typeof filterResult !== "string") {
                     filterResult = (await filterResult) ?? "include";
                     options.signal?.throwIfAborted();
@@ -177,7 +208,7 @@ export async function* walkRoot(root, relativePath, options) {
                     yield onLimit(child);
                     return;
                 }
-                yield* visit(child, depth + 1);
+                yield* visit(child, depth + 1, options.symlinkPolicy === "include" ? path.join(canonicalDirectory, name) : undefined);
                 if (truncated)
                     return;
             }

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, normalizeSafePathSegment, sanitizeSafePathSegment, trimHyphenEdges, } from "./safe-path-segment.js";
+import { assertSafePathSegment, isSafePathSegment, normalizeSafePathSegment, trimHyphenEdges, } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { hasNodeErrorCode } from "./path.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
@@ -62,7 +62,8 @@ function sanitizeExtension(extension) {
 export function sanitizeTempFileName(fileName) {
     // Suffix reserved stems before admission so CON.txt stays CON_.txt.
     const suffixed = suffixWindowsReservedDeviceName(normalizeSafePathSegment(path.basename(fileName)));
-    return sanitizeSafePathSegment(suffixed) ?? "download.bin";
+    // The suffix only inserts "_", so this value is already normalized.
+    return isSafePathSegment(suffixed, { allowDotPrefix: true }) ? suffixed : "download.bin";
 }
 export function buildRandomTempFilePath(params) {
     const rootDir = resolveTempRoot(params.rootDir);

package/dist/temp-workspace-admission.js

@@ -36,20 +36,21 @@ function copyExactDirectoryObservation(stat) {
         dev: stat.dev,
         ino: stat.ino,
         uid: stat.uid,
+        gid: stat.gid,
         mode: stat.mode,
         directory: stat.isDirectory(),
         symbolicLink: stat.isSymbolicLink(),
     });
 }
-function snapshotFromExactObservation(dir, uid, realPath, stat) {
+function snapshotFromExactObservation(dir, uid, realPath, stat, privateDirectory = false) {
     if (stat.symbolicLink || !stat.directory) {
         throw new FsSafeError("not-file", "temp workspace root component must be a real directory");
     }
-    assertTrustedTempWorkspaceDirectory(stat, uid);
+    assertTrustedTempWorkspaceDirectory(stat, uid, privateDirectory);
     const identity = Object.freeze({ dev: stat.dev, ino: stat.ino });
     // Retain copied immutable scalars, never a mutable Stats object supplied by
     // an observation hook. Every later permission check uses a fresh snapshot.
-    return Object.freeze({ dir, identity, numericIdentity: safeNumericIdentity(stat), realPath });
+    return Object.freeze({ dir, identity, numericIdentity: safeNumericIdentity(stat), realPath, privateDirectory });
 }
 function canonicalTempWorkspacePath(dir) {
     assertNoWindowsPathAlias(dir, "filesystem");
@@ -57,10 +58,10 @@ function canonicalTempWorkspacePath(dir) {
     assertNoWindowsPathAlias(canonical, "filesystem");
     return canonical;
 }
-function snapshot(dir, uid, realPath = canonicalTempWorkspacePath(dir)) {
+function snapshot(dir, uid, realPath = canonicalTempWorkspacePath(dir), privateDirectory = false) {
     const stat = inspectDirectoryIdentitySync(dir);
     const observation = copyExactDirectoryObservation(stat);
-    return { entry: snapshotFromExactObservation(dir, uid, realPath, observation), stat };
+    return { entry: snapshotFromExactObservation(dir, uid, realPath, observation, privateDirectory), stat };
 }
 function hasCompleteExactIdentity(stat) {
     return typeof stat.dev === "bigint" && typeof stat.ino === "bigint" &&
@@ -105,16 +106,16 @@ function inspectSnapshotIdentity(entry) {
 }
 function assertSnapshot(entry, uid) {
     const stat = inspectSnapshotIdentity(entry);
-    assertTrustedTempWorkspaceDirectory(stat, uid);
+    assertTrustedTempWorkspaceDirectory(stat, uid, entry.privateDirectory);
     assertCanonicalRoot(entry);
 }
-function snapshotMissingRootComponent(parent, dir, ownerUid) {
+function snapshotMissingRootComponent(parent, dir, ownerUid, privateDirectory) {
     if (parent.dir !== parent.realPath) {
         assertSnapshot(parent, ownerUid);
-        return snapshot(dir, ownerUid);
+        return snapshot(dir, ownerUid, undefined, privateDirectory);
     }
     const current = inspectSnapshotIdentity(parent);
-    assertTrustedTempWorkspaceDirectory(current, ownerUid);
+    assertTrustedTempWorkspaceDirectory(current, ownerUid, parent.privateDirectory);
     let realPath;
     try {
         realPath = canonicalTempWorkspacePath(dir);
@@ -126,16 +127,16 @@ function snapshotMissingRootComponent(parent, dir, ownerUid) {
     }
     if (path.dirname(realPath) !== parent.realPath) {
         assertCanonicalRoot(parent);
-        return snapshot(dir, ownerUid);
+        return snapshot(dir, ownerUid, undefined, privateDirectory);
     }
     // The child's canonical parent confirms the same parent name at this phase.
     // Its exact non-symlink/owner observation still precedes mode initialization.
-    return snapshot(dir, ownerUid, realPath);
+    return snapshot(dir, ownerUid, realPath, privateDirectory);
 }
 function assertChain(chain, uid) {
     for (const entry of chain) {
         const current = inspectSnapshotIdentity(entry);
-        assertTrustedTempWorkspaceDirectory(current, uid);
+        assertTrustedTempWorkspaceDirectory(current, uid, entry.privateDirectory);
     }
     const last = chain[chain.length - 1];
     assertCanonicalRoot(last);
@@ -158,7 +159,7 @@ function associateTempWorkspaceRoot(entry, ownerUid, descriptorFd) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw new FsSafeError("not-file", "temp workspace cleanup parent must be a real directory");
     }
-    assertTrustedTempWorkspaceDirectory(stat, ownerUid);
+    assertTrustedTempWorkspaceDirectory(stat, ownerUid, entry.privateDirectory);
 }
 function discoverMissingTempWorkspaceAncestor(ancestor, missing, missingError) {
     // The caller already classified the first ENOENT. Keep this handoff out of
@@ -219,14 +220,14 @@ function rootPlan(rootDir) {
     const existingCanonicalRoot = missing.length === 0 && observedAncestor === ancestor &&
         !initial.symbolicLink && initial.directory && hasCompleteExactIdentity(initial);
     if (existingCanonicalRoot) {
-        const discovery = snapshotFromExactObservation(ancestor, ownerUid, ancestor, initial);
+        const discovery = snapshotFromExactObservation(ancestor, ownerUid, ancestor, initial, true);
         return {
             admission: canonicalRootAdmission(discovery, ownerUid),
             missing,
             ownerUid,
         };
     }
-    const chain = canonicalAncestry(ancestor).map((dir) => snapshot(dir, ownerUid, dir).entry);
+    const chain = canonicalAncestry(ancestor).map((dir) => snapshot(dir, ownerUid, dir, missing.length === 0 && dir === ancestor).entry);
     // Missing-component creation needs a replay before its first mutation. When
     // the complete root already exists through an alias, retain the historical
     // guarded route because discovery and mutation use different path spellings.
@@ -286,10 +287,10 @@ function canonicalRootAdmission(discovery, ownerUid) {
             const ancestry = canonicalAncestry(discovery.dir);
             const candidate = ancestry.map((dir, index) => {
                 if (!TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY || index !== ancestry.length - 1) {
-                    return snapshot(dir, ownerUid, dir).entry;
+                    return snapshot(dir, ownerUid, dir, index === ancestry.length - 1 && discovery.privateDirectory).entry;
                 }
                 const current = inspectSnapshotIdentity(discovery);
-                assertTrustedTempWorkspaceDirectory(current, ownerUid);
+                assertTrustedTempWorkspaceDirectory(current, ownerUid, discovery.privateDirectory);
                 return discovery;
             });
             const current = candidate[candidate.length - 1];
@@ -332,7 +333,7 @@ export async function admitTempWorkspaceRoot(rootDir) {
     if (admission)
         return admission;
     const guardedChain = chain;
-    for (const segment of missing) {
+    for (const [index, segment] of missing.entries()) {
         const parentEntry = guardedChain[guardedChain.length - 1];
         const parent = rootAdmission(guardedChain, ownerUid);
         const dir = path.join(parent.dir, segment);
@@ -347,7 +348,7 @@ export async function admitTempWorkspaceRoot(rootDir) {
             if (error.code !== "EEXIST")
                 throw error;
         }
-        const observed = snapshotMissingRootComponent(parentEntry, dir, ownerUid);
+        const observed = snapshotMissingRootComponent(parentEntry, dir, ownerUid, index === missing.length - 1);
         if (created) {
             const modeInitialization = admitTempWorkspaceChild(dir, observed.stat, parent, 0o700);
             if (modeInitialization)
@@ -362,7 +363,7 @@ export function admitTempWorkspaceRootSync(rootDir) {
     if (admission)
         return admission;
     const guardedChain = chain;
-    for (const segment of missing) {
+    for (const [index, segment] of missing.entries()) {
         const parentEntry = guardedChain[guardedChain.length - 1];
         const parent = rootAdmission(guardedChain, ownerUid);
         const dir = path.join(parent.dir, segment);
@@ -377,7 +378,7 @@ export function admitTempWorkspaceRootSync(rootDir) {
             if (error.code !== "EEXIST")
                 throw error;
         }
-        const observed = snapshotMissingRootComponent(parentEntry, dir, ownerUid);
+        const observed = snapshotMissingRootComponent(parentEntry, dir, ownerUid, index === missing.length - 1);
         if (created)
             admitTempWorkspaceChildSync(dir, observed.stat, parent, 0o700);
         guardedChain.push(observed.entry);

package/dist/temp-workspace-child-admission.d.ts

@@ -14,7 +14,7 @@ export declare function projectTempWorkspaceNumericIdentity(identity: TempWorksp
 export declare function inspectTempWorkspaceDescriptorIdentitySync(fd: number, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
 export declare function inspectTempWorkspaceDirectoryIdentitySync(dir: string, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
 export declare function validateTempWorkspaceDirMode(mode: number): void;
-export declare function assertTrustedTempWorkspaceDirectory(stat: Pick<BigIntStats, "uid" | "mode"> | Pick<Stats, "uid" | "mode">, uid: number | undefined, child?: boolean): void;
+export declare function assertTrustedTempWorkspaceDirectory(stat: Pick<BigIntStats, "uid" | "gid" | "mode"> | Pick<Stats, "uid" | "gid" | "mode">, uid: number | undefined, privateDirectory?: boolean): void;
 export declare function assertTempWorkspaceChildState(stat: BigIntStats | Stats, ownerUid: number | undefined): void;
 export declare function validateInitialTempWorkspaceChild(stat: BigIntStats, ownerUid: number | undefined, mode: number): boolean;
 export declare function childHasRequestedMode(stat: BigIntStats | Stats, mode: number): boolean;