@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/staged-directory.d.ts

@@ -1,16 +1,25 @@
+import { type BigIntStats } from "node:fs";
 import type { DirectoryReceipt } from "./directory-durability.js";
 import type { FileIdentityStat } from "./file-identity.js";
+import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
 import type { StagedFileReceipt } from "./staged-file-types.js";
-type DirectorySnapshot = StagedFileReceipt["directory"];
+export type StagedDirectorySnapshot = StagedFileReceipt["directory"];
+export type PolicyStagedDirectory = Readonly<{
+    directory: StagedDirectorySnapshot;
+    observation: MutationDirectoryObservation;
+    stat: BigIntStats;
+}>;
 export declare function exactIdentityMatches(expected: FileIdentityStat, actual: Readonly<{
     dev: bigint;
     ino: bigint;
 }>): boolean;
-export declare function describeStagedDirectory(fd: number, pathname: string): DirectorySnapshot;
-export declare function assertStagedDirectoryCurrent(receipt: DirectorySnapshot): void;
+export declare function describeStagedDirectory(fd: number, pathname: string): StagedDirectorySnapshot;
+export declare function assertStagedDirectoryCurrent(receipt: StagedDirectorySnapshot): BigIntStats;
+export declare function describePolicyStagedDirectory(fd: number, pathname: string): PolicyStagedDirectory;
+export declare function assertPolicyStagedDirectoryCurrent(captured: PolicyStagedDirectory): BigIntStats;
+export declare function refreshPolicyStagedDirectoryObservation(captured: PolicyStagedDirectory): MutationDirectoryObservation;
 export declare function openStagedDirectory(directory: string | DirectoryReceipt): {
     fd: number;
-    receipt: DirectorySnapshot;
+    receipt: StagedDirectorySnapshot;
 };
-export {};
 //# sourceMappingURL=staged-directory.d.ts.map

package/dist/staged-directory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,KAAK,iBAAiB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAExD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAYvF;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAQ7E;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CA+BA"}
+{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAY7F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAS1F;AASD,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAwBvB;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,qBAAqB,GAC9B,WAAW,CAOb;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,qBAAqB,GAC9B,4BAA4B,CAU9B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAiCA"}

package/dist/staged-directory.js

@@ -1,7 +1,10 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
 import { realpathSync } from "./realpath.js";
+import { resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
 export function exactIdentityMatches(expected, actual) {
     return ["dev", "ino"].every((key) => {
         const value = expected[key];
@@ -14,7 +17,7 @@ export function describeStagedDirectory(fd, pathname) {
         throw new FsSafeError("not-file", "staging parent must be a directory");
     }
     const receipt = Object.freeze({
-        path: path.resolve(pathname),
+        path: resolvePathPreservingWindowsRoot(pathname),
         realPath: realpathSync(pathname),
         identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
     });
@@ -27,10 +30,58 @@ export function assertStagedDirectoryCurrent(receipt) {
         realpathSync(receipt.path) !== receipt.realPath) {
         throw new FsSafeError("path-mismatch", "staging directory pathname changed");
     }
+    return current;
+}
+function sameDirectoryMetadata(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.nlink === right.nlink;
+}
+// The policy hot path is Node/POSIX-only. It deliberately uses native
+// canonicalization so a successful capture contains no JS realpath work.
+export function describePolicyStagedDirectory(fd, pathname) {
+    const resolved = path.resolve(pathname);
+    const descriptor = fs.fstatSync(fd, { bigint: true });
+    if (!descriptor.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a directory");
+    }
+    const before = inspectDirectoryIdentitySync(resolved);
+    const canonicalPath = path.resolve(realpathSync.native(resolved));
+    const after = inspectDirectoryIdentitySync(resolved, descriptor);
+    if (canonicalPath !== resolved || !sameDirectoryMetadata(descriptor, before) ||
+        !sameDirectoryMetadata(descriptor, after) ||
+        path.resolve(realpathSync.native(resolved)) !== canonicalPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+    const directory = Object.freeze({
+        path: resolved,
+        realPath: canonicalPath,
+        identity: Object.freeze({ dev: descriptor.dev, ino: descriptor.ino }),
+    });
+    return Object.freeze({
+        directory,
+        observation: checkedMutationDirectory(resolved, canonicalPath, after),
+        stat: after,
+    });
+}
+export function assertPolicyStagedDirectoryCurrent(captured) {
+    const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
+    if (!sameDirectoryMetadata(captured.stat, current) ||
+        path.resolve(realpathSync.native(captured.directory.path)) !== captured.directory.realPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+    return current;
+}
+export function refreshPolicyStagedDirectoryObservation(captured) {
+    const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
+    const canonicalPath = path.resolve(realpathSync.native(captured.directory.path));
+    if (canonicalPath !== captured.directory.realPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+    return checkedMutationDirectory(captured.directory.path, canonicalPath, current);
 }
 export function openStagedDirectory(directory) {
     // Copy supplied facts before any asynchronous work; receipts are not authority.
-    const pathname = path.resolve(typeof directory === "string" ? directory : directory.path);
+    const pathname = resolvePathPreservingWindowsRoot(typeof directory === "string" ? directory : directory.path);
     const expected = typeof directory === "string" ? undefined : {
         realPath: directory.realPath, dev: directory.identity.dev, ino: directory.identity.ino,
     };

package/dist/standalone-publication-path.d.ts

@@ -0,0 +1,2 @@
+export declare function admitStandalonePublicationPath(value: string, message?: string): string;
+//# sourceMappingURL=standalone-publication-path.d.ts.map

package/dist/standalone-publication-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone-publication-path.d.ts","sourceRoot":"","sources":["../src/standalone-publication-path.ts"],"names":[],"mappings":"AAKA,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAItF"}

package/dist/standalone-publication-path.js

@@ -0,0 +1,6 @@
+import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias, } from "./windows-path-alias.js";
+export function admitStandalonePublicationPath(value, message) {
+    const admittedPath = anchorWindowsDriveRelativePath(value);
+    assertNoWindowsPathAlias(admittedPath, "filesystem", message);
+    return admittedPath;
+}

package/dist/stat-observation.d.ts

@@ -0,0 +1,11 @@
+import type { BigIntStats, Stats } from "node:fs";
+export type ExactStatIdentity = Pick<BigIntStats, "dev" | "ino">;
+export type StatObservationReceipt = {
+    stat: Stats | BigIntStats;
+    identity: ExactStatIdentity;
+};
+/** Operation-local metadata plus exact identity; never use projected PathStat IDs. */
+export declare function inspectStatObservationSync(inspect: (bigint: boolean) => Stats | BigIntStats, expected?: ExactStatIdentity, initial?: Stats | BigIntStats, platform?: NodeJS.Platform): StatObservationReceipt;
+/** Revalidate an exact identity without allocating a receipt that the caller will discard. */
+export declare function assertStatObservationSync(inspect: (bigint: boolean) => Stats | BigIntStats, expected: ExactStatIdentity, initial?: Stats | BigIntStats, platform?: NodeJS.Platform): Stats | BigIntStats;
+//# sourceMappingURL=stat-observation.d.ts.map

package/dist/stat-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stat-observation.d.ts","sourceRoot":"","sources":["../src/stat-observation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAKlD,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AACjE,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,KAAK,GAAG,WAAW,CAAC;IAC1B,QAAQ,EAAE,iBAAiB,CAAC;CAC7B,CAAC;AAqEF,sFAAsF;AACtF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,GAAG,WAAW,EACjD,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,OAAO,CAAC,EAAE,KAAK,GAAG,WAAW,EAC7B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,sBAAsB,CAExB;AAED,8FAA8F;AAC9F,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,GAAG,WAAW,EACjD,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,CAAC,EAAE,KAAK,GAAG,WAAW,EAC7B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,KAAK,GAAG,WAAW,CAErB"}

package/dist/stat-observation.js

@@ -0,0 +1,64 @@
+import { FsSafeError } from "./errors.js";
+import { recordFileObservationFailure } from "./file-observation.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+function identityMismatch() {
+    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+    recordFileObservationFailure(error, "identity");
+    throw error;
+}
+function safeNumber(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function safeExpected(identity) {
+    return typeof identity.dev === "bigint" && typeof identity.ino === "bigint" &&
+        identity.dev >= 0n && identity.ino >= 0n &&
+        identity.dev <= 9007199254740991n && identity.ino <= 9007199254740991n;
+}
+function observeStatSync(inspect, expected, initial, platform = process.platform, captureIdentity) {
+    if (platform === "win32" || (!initial && expected && !safeExpected(expected))) {
+        // Preserve the strict Windows unknown-ID retry, including known components
+        // and validation of the expected identity before the first observation.
+        const stat = inspectFileIdentitySync(() => {
+            const current = initial;
+            initial = undefined;
+            return (current ?? inspect(true));
+        }, expected, platform);
+        return (captureIdentity
+            ? { stat, identity: expected ?? { dev: stat.dev, ino: stat.ino } }
+            : stat);
+    }
+    const stat = initial ?? inspect(false);
+    const { dev: rawDev, ino: rawIno } = stat;
+    const numericDev = safeNumber(rawDev);
+    const numericIno = safeNumber(rawIno);
+    const dev = numericDev ? BigInt(rawDev) : typeof rawDev === "bigint" ? rawDev : undefined;
+    const ino = numericIno ? BigInt(rawIno) : typeof rawIno === "bigint" ? rawIno : undefined;
+    if (expected && ((dev !== undefined && dev !== expected.dev) ||
+        (ino !== undefined && ino !== expected.ino)))
+        identityMismatch();
+    if (numericDev && numericIno) {
+        return (captureIdentity
+            ? { stat, identity: expected ?? { dev: dev, ino: ino } }
+            : stat);
+    }
+    // An unsafe numeric component is unknown, not a rounded identity. Retain
+    // every exact component from this observation while obtaining the full ID.
+    const exact = inspectFileIdentitySync(() => {
+        const current = inspect(true);
+        if ((dev !== undefined && current.dev !== dev) ||
+            (ino !== undefined && current.ino !== ino))
+            identityMismatch();
+        return current;
+    }, expected, platform);
+    return (captureIdentity
+        ? { stat: exact, identity: expected ?? { dev: exact.dev, ino: exact.ino } }
+        : exact);
+}
+/** Operation-local metadata plus exact identity; never use projected PathStat IDs. */
+export function inspectStatObservationSync(inspect, expected, initial, platform = process.platform) {
+    return observeStatSync(inspect, expected, initial, platform, true);
+}
+/** Revalidate an exact identity without allocating a receipt that the caller will discard. */
+export function assertStatObservationSync(inspect, expected, initial, platform = process.platform) {
+    return observeStatSync(inspect, expected, initial, platform, false);
+}

package/dist/strict-file-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA+B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7B,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAOH"}
+{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA+B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7B,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAmCH"}

package/dist/strict-file-identity.js

@@ -41,10 +41,47 @@ export async function inspectFileIdentity(inspect, expected, platform = process.
     throw identityMismatch();
 }
 export function inspectFileIdentitySync(inspect, expected, platform = process.platform) {
-    const check = identityCheck(expected, platform);
+    let knownDev;
+    let knownIno;
+    if (expected) {
+        knownDev = expected.dev;
+        if (typeof knownDev !== "bigint")
+            throw identityMismatch();
+        knownIno = expected.ino;
+        if (typeof knownIno !== "bigint")
+            throw identityMismatch();
+        // An unknown expected device must not bypass observation of its inode.
+        if (platform === "win32" && (knownDev === 0n || knownIno === 0n))
+            throw identityMismatch();
+    }
     for (let attempt = 0; attempt < 2; attempt++) {
         const stat = inspect();
-        if (check(stat))
+        let complete = true;
+        // Keep dev-before-ino access and early mismatch errors without allocating
+        // a checker closure, known-component object, or field array per inspection.
+        const dev = stat.dev;
+        if (typeof dev !== "bigint")
+            throw identityMismatch();
+        if (platform === "win32" && dev === 0n) {
+            complete = false;
+        }
+        else {
+            if (knownDev !== undefined && knownDev !== dev)
+                throw identityMismatch();
+            knownDev = dev;
+        }
+        const ino = stat.ino;
+        if (typeof ino !== "bigint")
+            throw identityMismatch();
+        if (platform === "win32" && ino === 0n) {
+            complete = false;
+        }
+        else {
+            if (knownIno !== undefined && knownIno !== ino)
+                throw identityMismatch();
+            knownIno = ino;
+        }
+        if (complete)
             return stat;
     }
     throw identityMismatch();

package/dist/symlink-parents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAyBF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA6BN"}
+{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAqCF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA6BN"}

package/dist/symlink-parents.js

@@ -2,9 +2,14 @@ import fsSync from "node:fs";
 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 resolvePathWalk(params) {
-    const root = path.resolve(params.rootDir);
-    const target = path.resolve(params.targetPath);
+    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);
     if (isPathRelativeEscape(relative)) {
         if (params.allowOutsideRoot) {

package/dist/temp-target.d.ts

@@ -1,4 +1,5 @@
 import fsSync from "node:fs";
+import type { TempWorkspaceCleanupSafety } from "./temp-workspace-owner.js";
 export type TempFile = {
     dir: string;
     path: string;
@@ -11,6 +12,7 @@ type TempFileOptions = {
     prefix: string;
     fileName?: string;
     onCleanupError?: (error: unknown) => void;
+    cleanupSafety?: TempWorkspaceCleanupSafety;
 };
 export declare function sanitizeTempFileName(fileName: string): string;
 export declare function buildRandomTempFilePath(params: {

package/dist/temp-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,SAAS,CAAC;AAQ7B,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyCD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC;IAC1E,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;CAC7D,CAAC,CA2BD;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEzE;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,SAAS,CAAC;AAa7B,OAAO,KAAK,EAEV,0BAA0B,EAC3B,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C,aAAa,CAAC,EAAE,0BAA0B,CAAC;CAC5C,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAeT;AAwDD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC;IAC1E,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;CAC7D,CAAC,CAmID;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEzE;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -2,10 +2,12 @@ import crypto from "node:crypto";
 import fsSync from "node:fs";
 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 { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 const HYPHEN_CHAR_CODE = 0x2d;
 const DOT_CHAR_CODE = 0x2e;
 const NUMBER_ZERO_CHAR_CODE = 0x30;
@@ -57,9 +59,10 @@ function sanitizeExtension(extension) {
     return token ? `.${token}` : "";
 }
 export function sanitizeTempFileName(fileName) {
-    return sanitizeSafePathSegment(path.basename(fileName), "download.bin", {
+    const sanitized = sanitizeSafePathSegment(path.basename(fileName), "download.bin", {
         allowDotPrefix: true,
     });
+    return suffixWindowsReservedDeviceName(sanitized);
 }
 export function buildRandomTempFilePath(params) {
     const rootDir = resolveTempRoot(params.rootDir);
@@ -72,7 +75,9 @@ export function buildRandomTempFilePath(params) {
     const uuid = params.uuid
         ? assertSafePathSegment(params.uuid.trim(), { label: "temp uuid" })
         : crypto.randomUUID();
-    return path.join(rootDir, `${prefix}-${now}-${uuid}${extension}`);
+    const filePath = path.join(rootDir, `${prefix}-${now}-${uuid}${extension}`);
+    assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+    return filePath;
 }
 function isNodeErrorWithCode(err, code) {
     return (typeof err === "object" &&
@@ -104,17 +109,141 @@ async function cleanupTempDir(dir, identity, onCleanupError) {
     }
 }
 function resolveTempRoot(rootDir) {
-    return path.resolve(rootDir ?? resolveSecureTempRoot({ fallbackPrefix: "fs-safe" }));
+    if (rootDir !== undefined) {
+        assertNoWindowsPathAlias(rootDir, "filesystem", "temp root uses a Windows filesystem namespace alias");
+    }
+    const selectedRoot = rootDir ?? resolveSecureTempRoot({ fallbackPrefix: "fs-safe" });
+    assertNoWindowsPathAlias(selectedRoot, "filesystem", "temp root uses a Windows filesystem namespace alias");
+    const resolvedRoot = resolvePathPreservingWindowsRoot(selectedRoot);
+    assertNoWindowsPathAlias(resolvedRoot, "filesystem", "temp root uses a Windows filesystem namespace alias");
+    return resolvedRoot;
+}
+function resolveTempFileCleanupSafety(value) {
+    if (value === undefined || value === "compatible")
+        return "compatible";
+    if (value === "require-bounded")
+        return value;
+    throw new TypeError("cleanupSafety must be compatible or require-bounded");
 }
 export async function createOwnedTempFile(params) {
+    const cleanupSafety = resolveTempFileCleanupSafety(params.cleanupSafety);
     const rootDir = resolveTempRoot(params.rootDir);
     const prefix = `${sanitizePrefix(params.prefix)}-`;
+    if (cleanupSafety === "require-bounded") {
+        const initialFileName = sanitizeTempFileName(params.fileName ?? "download.bin");
+        const [{ TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner }, { admitExistingTempWorkspaceRoot }, { TempWorkspaceRetainedChild }, { validateInitialTempWorkspaceChild, admitRetainedTempWorkspaceChild }, { inspectDirectoryIdentitySync },] = await Promise.all([
+            import("./temp-workspace-owner.js"),
+            import("./temp-workspace-admission.js"),
+            import("./temp-workspace-descriptor.js"),
+            import("./temp-workspace-child-admission.js"),
+            import("./directory-guard.js"),
+        ]);
+        const admission = admitExistingTempWorkspaceRoot(rootDir);
+        const childPrefix = path.join(admission.dir, prefix);
+        assertNoWindowsPathAlias(childPrefix, "filesystem", "temp directory uses a Windows filesystem namespace alias");
+        const capability = new TempWorkspaceCleanupCapability(admission.dir, cleanupSafety, admission, 0o700);
+        let dir;
+        let initialPath;
+        let identity;
+        let retainedChild;
+        let cleanupOwner;
+        let unregisterTempDir;
+        try {
+            capability.prepareChildCreation();
+            dir = await fs.mkdtemp(childPrefix);
+            assertNoWindowsPathAlias(dir, "filesystem", "temp directory uses a Windows filesystem namespace alias");
+            initialPath = path.join(dir, initialFileName);
+            assertNoWindowsPathAlias(initialPath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+            capability.assertCurrent();
+            const initial = inspectDirectoryIdentitySync(dir);
+            identity = Object.freeze({ dev: initial.dev, ino: initial.ino });
+            const needsModeInitialization = validateInitialTempWorkspaceChild(initial, admission.ownerUid, 0o700);
+            retainedChild = TempWorkspaceRetainedChild.retain(dir, identity);
+            const modeInitialization = admitRetainedTempWorkspaceChild(retainedChild, needsModeInitialization, admission, 0o700);
+            if (modeInitialization)
+                await modeInitialization;
+            const retainDescriptor = capability.admitChildDescriptor(retainedChild.ensureReadable());
+            capability.assertAncestryCurrent();
+            retainedChild.finalizeAdmission(admission.ownerUid, 0o700);
+            cleanupOwner = new TempWorkspaceCleanupOwner(retainedChild, capability, retainDescriptor);
+            retainedChild = undefined;
+            unregisterTempDir = registerTempPathForExit(dir, {
+                cleanupSync: () => cleanupOwner.cleanupSync(),
+            });
+        }
+        catch (error) {
+            try {
+                if (cleanupOwner)
+                    cleanupOwner.cleanupSync();
+                else {
+                    const closeErrors = [];
+                    try {
+                        retainedChild?.close();
+                    }
+                    catch (closeError) {
+                        closeErrors.push(closeError);
+                    }
+                    try {
+                        capability.close();
+                    }
+                    catch (closeError) {
+                        closeErrors.push(closeError);
+                    }
+                    if (closeErrors.length === 1)
+                        throw closeErrors[0];
+                    if (closeErrors.length > 1) {
+                        throw new AggregateError(closeErrors, "temp file admission descriptor close failed");
+                    }
+                }
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], "temp file creation and cleanup both failed");
+            }
+            throw error;
+        }
+        const owner = cleanupOwner;
+        const file = (fileName) => {
+            const filePath = path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
+            assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+            return filePath;
+        };
+        const cleanup = async () => {
+            try {
+                try {
+                    await owner.cleanup();
+                }
+                catch (err) {
+                    if (!isNodeErrorWithCode(err, "ENOENT")) {
+                        params.onCleanupError?.(err);
+                    }
+                }
+            }
+            finally {
+                unregisterTempDir();
+            }
+        };
+        return {
+            target: {
+                dir,
+                path: initialPath,
+                file,
+                cleanup,
+                [Symbol.asyncDispose]: cleanup,
+            },
+            identity,
+        };
+    }
     const dir = await fs.mkdtemp(path.join(rootDir, prefix));
+    assertNoWindowsPathAlias(dir, "filesystem", "temp directory uses a Windows filesystem namespace alias");
     // Windows file indexes can exceed Number.MAX_SAFE_INTEGER. Cleanup receipts
     // must retain the exact identity or adjacent directories can compare equal.
     const identity = fsSync.lstatSync(dir, { bigint: true });
     const unregisterTempDir = registerTempPathForExit(dir, { recursive: true, identity });
-    const file = (fileName) => path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
+    const file = (fileName) => {
+        const filePath = path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
+        assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+        return filePath;
+    };
     const cleanup = async () => {
         try {
             await cleanupTempDir(dir, identity, params.onCleanupError);

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

@@ -0,0 +1,22 @@
+type ExactIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type TempWorkspaceRootAdmission = {
+    dir: string;
+    identity: ExactIdentity;
+    ownerUid: number | undefined;
+    realPath: string;
+    retainCleanupParent(descriptorFd: number): void;
+    prepareCleanupProbe(descriptorFd: number): void;
+    prepareChildCreation(descriptorFd?: number): void;
+    assertCurrent(): void;
+    assertAncestry(): void;
+    associateCurrent(descriptorFd: number): void;
+    associateAncestry(descriptorFd: number): void;
+};
+export declare function admitExistingTempWorkspaceRoot(rootDir: string): TempWorkspaceRootAdmission;
+export declare function admitTempWorkspaceRoot(rootDir: string): Promise<TempWorkspaceRootAdmission>;
+export declare function admitTempWorkspaceRootSync(rootDir: string): TempWorkspaceRootAdmission;
+export {};
+//# sourceMappingURL=temp-workspace-admission.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"temp-workspace-admission.d.ts","sourceRoot":"","sources":["../src/temp-workspace-admission.ts"],"names":[],"mappings":"AA6BA,KAAK,aAAa,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAiB5D,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,oBAAoB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,aAAa,IAAI,IAAI,CAAC;IACtB,cAAc,IAAI,IAAI,CAAC;IACvB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C,CAAC;AA0UF,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAM1F;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyBjG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAsBtF"}