@openclaw/fs-safe 0.12.0 → 0.13.0

package/dist/secret-read-async.js

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

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

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

package/dist/secret-read-policy.js

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

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

@@ -1 +1 @@
-{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAe,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAc/D,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAK1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAuNF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CA6B/B"}
+{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAe,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAe/D,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAU1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAgTF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAgC/B"}

package/dist/secure-file.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { readFileHandleBounded } from "./bounded-read.js";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
+import { resolveEffectiveUid } from "./effective-uid.js";
 import { FsSafeError } from "./errors.js";
 import { isWindowsDriveLetterPath, isWindowsNetworkPath } from "./local-file-access.js";
 import { isPathInside, isSymlinkOpenError } from "./path.js";
@@ -14,6 +15,75 @@ import { inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadab
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { inspectSecureWindowsDescriptor } from "./secure-file-windows.js";
 import { scheduleTimeout } from "./timing.js";
+import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function snapshotTrustedDirs(dirs) {
+    if (dirs === undefined)
+        return undefined;
+    if (!Array.isArray(dirs)) {
+        throw new FsSafeError("invalid-path", "trustedDirs must be an array of path strings.");
+    }
+    const trustedDirs = [];
+    const length = dirs.length;
+    if (!Number.isSafeInteger(length) || length < 0 || length > 0xffff_ffff) {
+        throw new FsSafeError("invalid-path", "trustedDirs must have a valid array length.");
+    }
+    for (let index = 0; index < length; index += 1) {
+        if (!Object.hasOwn(dirs, index)) {
+            throw new FsSafeError("invalid-path", "trustedDirs must not contain sparse entries.");
+        }
+        const dir = dirs[index];
+        if (typeof dir !== "string" || dir.includes("\0")) {
+            throw new FsSafeError("invalid-path", "trustedDirs must contain only path strings without null bytes.");
+        }
+        // Admit the raw suffix before normalization can erase an alternate stream,
+        // while retaining Node's per-drive cwd semantics for D:credentials.
+        const anchored = anchorWindowsDriveRelativePath(dir);
+        assertNoWindowsPathAlias(anchored, "filesystem", "trusted directory uses a Windows filesystem namespace alias");
+        const resolved = resolvePathPreservingWindowsRoot(anchored);
+        assertNoWindowsPathAlias(resolved, "filesystem", "trusted directory uses a Windows filesystem namespace alias");
+        trustedDirs.push(resolved);
+    }
+    return trustedDirs;
+}
+function snapshotPermissionEnv(env) {
+    if (env === undefined)
+        return undefined;
+    const snapshot = { ...env };
+    // Windows command lookup first reads these exact names, even when inherited
+    // or non-enumerable, then considers only enumerable own case variants.
+    // Reuse copied values so enumerable getters are not invoked a second time.
+    if (!Object.hasOwn(snapshot, "SystemRoot"))
+        snapshot.SystemRoot = env.SystemRoot;
+    if (!Object.hasOwn(snapshot, "WINDIR"))
+        snapshot.WINDIR = env.WINDIR;
+    return snapshot;
+}
+function snapshotSecureFileOptions(options, io, maxBytes) {
+    const { filePath, label, trust, permissions, inject } = options;
+    const env = inject?.env;
+    return {
+        filePath,
+        label,
+        trust: {
+            trustedDirs: snapshotTrustedDirs(trust?.trustedDirs),
+            allowSymlink: trust?.allowSymlink,
+            allowNetworkPath: trust?.allowNetworkPath,
+        },
+        permissions: {
+            allowInsecure: permissions?.allowInsecure,
+            allowReadableByOthers: permissions?.allowReadableByOthers,
+        },
+        inject: {
+            platform: inject?.platform,
+            env: snapshotPermissionEnv(env),
+            exec: inject?.exec,
+        },
+        io: {
+            maxBytes,
+            timeoutMs: io?.timeoutMs,
+        },
+    };
+}
 function isAbsolutePathname(value) {
     return (path.isAbsolute(value) ||
         (process.platform === "win32" &&
@@ -82,6 +152,7 @@ async function openSecureHandle(options, maxBytes) {
             return pathStat;
         }, openedIdentity);
         const realPath = realpathSync.native(options.filePath);
+        assertNoWindowsPathAlias(realPath, "filesystem", `${label(options)} resolved path uses a Windows filesystem namespace alias`);
         await inspectFileIdentity(() => {
             const realPathStat = fsSync.statSync(realPath, { bigint: true });
             assertNotHardlinked(options, realPathStat);
@@ -102,13 +173,15 @@ async function assertTrustedDirs(options, realPath) {
         return;
     }
     const trusted = await Promise.all(options.trust.trustedDirs.map(async (dir) => {
-        const resolved = path.resolve(dir);
+        let realPath;
         try {
-            return realpathSync.native(resolved);
+            realPath = realpathSync.native(dir);
         }
         catch {
-            return resolved;
+            return dir;
         }
+        assertNoWindowsPathAlias(realPath, "filesystem", "trusted directory uses a Windows filesystem namespace alias");
+        return realPath;
     }));
     if (!trusted.some((dir) => isPathInside(dir, realPath))) {
         throw new FsSafeError("outside-workspace", `${label(options)} is outside trustedDirs: ${realPath}`);
@@ -163,10 +236,19 @@ async function assertSecurePermissions(options, stat, realPath, identity, fd) {
     if (writableByOthers || (!options.permissions?.allowReadableByOthers && readableByOthers)) {
         throw new FsSafeError("insecure-permissions", `${label(options)} permissions are too open: ${realPath}`);
     }
-    if (platform !== "win32" && typeof process.getuid === "function" && stat.uid != null) {
-        const uid = process.getuid();
+    if (platform !== "win32") {
+        let uid;
+        try {
+            uid = resolveEffectiveUid();
+        }
+        catch (cause) {
+            throw new FsSafeError("permission-unverified", `${label(options)} owner identity could not be verified for the effective user: ${realPath}`, { cause });
+        }
+        if (uid === undefined || !Number.isSafeInteger(stat.uid) || stat.uid < 0) {
+            throw new FsSafeError("permission-unverified", `${label(options)} owner identity could not be verified for the effective user: ${realPath}`);
+        }
         if (stat.uid !== uid) {
-            throw new FsSafeError("not-owned", `${label(options)} must be owned by the current user (uid=${uid}): ${realPath}`);
+            throw new FsSafeError("not-owned", `${label(options)} must be owned by the effective user (uid=${uid}): ${realPath}`);
         }
     }
     return permissions;
@@ -193,7 +275,10 @@ async function readHandleWithTimeout(handle, timeoutMs, maxBytes) {
     }
 }
 export async function readSecureFile(options) {
-    const maxBytes = normalizeMaxBytes(options.io?.maxBytes);
+    const io = options.io;
+    const maxBytes = normalizeMaxBytes(io?.maxBytes);
+    options = snapshotSecureFileOptions(options, io, maxBytes);
+    assertNoWindowsPathAlias(options.filePath, "filesystem", `${label(options)} path uses a Windows filesystem namespace alias`);
     const opened = await openSecureHandle(options, maxBytes);
     try {
         await assertTrustedDirs(options, opened.realPath);

package/dist/secure-temp-dir.d.ts

@@ -1,12 +1,16 @@
+import { type SecureTempRootDescriptorAdapter } from "./secure-temp-repair.js";
+export type { SecureTempRootDescriptorAdapter } from "./secure-temp-repair.js";
 type SecureDirStat = {
     isDirectory(): boolean;
     isSymbolicLink(): boolean;
-    mode?: number;
-    uid?: number;
+    mode?: number | bigint;
+    uid?: number | bigint;
 };
 export type ResolveSecureTempRootOptions = {
     accessSync?: (path: string, mode?: number) => void;
+    /** @deprecated Unused. Repairs require descriptor-bound chmod. */
     chmodSync?: (path: string, mode: number) => void;
+    descriptor?: SecureTempRootDescriptorAdapter;
     fallbackPrefix: string;
     getuid?: () => number | undefined;
     lstatSync?: (path: string) => SecureDirStat;
@@ -23,5 +27,4 @@ export type ResolveSecureTempRootOptions = {
     warningPrefix?: string;
 };
 export declare function resolveSecureTempRoot(options: ResolveSecureTempRootOptions): string;
-export {};
 //# sourceMappingURL=secure-temp-dir.d.ts.map

package/dist/secure-temp-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-temp-dir.d.ts","sourceRoot":"","sources":["../src/secure-temp-dir.ts"],"names":[],"mappings":"AAQA,KAAK,aAAa,GAAG;IACnB,WAAW,IAAI,OAAO,CAAC;IACvB,cAAc,IAAI,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,CAAC;IAC5C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAWF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CA+JnF"}
+{"version":3,"file":"secure-temp-dir.d.ts","sourceRoot":"","sources":["../src/secure-temp-dir.ts"],"names":[],"mappings":"AAOA,OAAO,EAKL,KAAK,+BAA+B,EACrC,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,+BAA+B,EAAE,MAAM,yBAAyB,CAAC;AAI/E,KAAK,aAAa,GAAG;IACnB,WAAW,IAAI,OAAO,CAAC;IACvB,cAAc,IAAI,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,kEAAkE;IAClE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,UAAU,CAAC,EAAE,+BAA+B,CAAC;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,CAAC;IAC5C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAWF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CA6LnF"}

package/dist/secure-temp-dir.js

@@ -1,8 +1,11 @@
 import fs from "node:fs";
 import { tmpdir as getOsTmpDir } from "node:os";
 import path from "node:path";
+import { directoryEntryPath } from "./directory-entry-path.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
+import { captureSecureTempRepairAdapter, repairSecureTempDirectory, secureTempDirectoryReceipt, } from "./secure-temp-repair.js";
 function isNodeErrorWithCode(err, code) {
     return (typeof err === "object" &&
         err !== null &&
@@ -10,152 +13,169 @@ function isNodeErrorWithCode(err, code) {
         err.code === code);
 }
 export function resolveSecureTempRoot(options) {
-    const fallbackPrefix = assertSafePathSegment(options.fallbackPrefix, {
+    const { fallbackPrefix: prefix, accessSync: suppliedAccess, lstatSync: suppliedLstat, mkdirSync: suppliedMkdir, descriptor: suppliedDescriptor, getuid: suppliedGetuid, tmpdir: suppliedTmpdir, platform: suppliedPlatform, preferredDir, skipPreferredOnWindows, warn: suppliedWarn, warningPrefix: suppliedWarningPrefix, unsafeFallbackLabel: suppliedFallbackLabel, } = options;
+    const platform = suppliedPlatform ?? process.platform;
+    const windows = process.platform === "win32" || platform === "win32";
+    // A platform adapter cannot disable the host's Windows pathname policy.
+    const admissionPlatform = process.platform === "win32" ? process.platform : platform;
+    const capturedDescriptor = captureSecureTempRepairAdapter(suppliedDescriptor, suppliedAccess !== undefined || suppliedLstat !== undefined || suppliedMkdir !== undefined);
+    const descriptor = windows ? undefined : capturedDescriptor;
+    const hostLstat = fs.lstatSync;
+    const hostAccess = fs.accessSync;
+    const hostMkdir = fs.mkdirSync;
+    const hostGetuid = process.getuid;
+    const accessSync = suppliedAccess ?? (process.platform === "win32"
+        ? (candidate, mode) => hostAccess(pathForWindowsFilesystem(candidate), mode)
+        : hostAccess);
+    const lstatSync = descriptor
+        ? (candidate) => descriptor.lstatSync(candidate, { bigint: true })
+        : suppliedLstat ?? ((candidate) => windows
+            ? hostLstat(pathForWindowsFilesystem(candidate))
+            : hostLstat(candidate, { bigint: true }));
+    // Virtual observations cannot authorize host creation. A supplied mkdir hook
+    // is explicit authority; chmodSync is deprecated and deliberately not read.
+    const mkdirSync = suppliedMkdir ?? (suppliedLstat !== undefined || suppliedAccess !== undefined || suppliedDescriptor !== undefined
+        ? undefined
+        : (directory, mkdirOptions) => hostMkdir(recursiveMkdirPath(pathForWindowsFilesystem(directory)), mkdirOptions));
+    const warn = suppliedWarn ?? console.warn.bind(console);
+    const warningPrefix = suppliedWarningPrefix ?? "[fs-safe]";
+    const unsafeFallbackLabel = suppliedFallbackLabel ?? "secure temp dir";
+    const tmpdir = typeof suppliedTmpdir === "function" ? suppliedTmpdir : getOsTmpDir;
+    const getuid = suppliedGetuid ?? (() => {
+        try {
+            return typeof hostGetuid === "function" ? hostGetuid.call(process) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    });
+    const fallbackPrefix = assertSafePathSegment(prefix, {
         allowDotPrefix: true,
         label: "fallback temp prefix",
     });
     const TMP_DIR_ACCESS_MODE = fs.constants.W_OK | fs.constants.X_OK;
-    const accessSync = options.accessSync ?? fs.accessSync;
-    const chmodSync = options.chmodSync ?? fs.chmodSync;
-    const lstatSync = options.lstatSync ?? fs.lstatSync;
-    const mkdirSync = options.mkdirSync ?? ((directory, mkdirOptions) => fs.mkdirSync(recursiveMkdirPath(directory), mkdirOptions));
-    const warn = options.warn ?? ((message) => console.warn(message));
-    const warningPrefix = options.warningPrefix ?? "[fs-safe]";
-    const unsafeFallbackLabel = options.unsafeFallbackLabel ?? "secure temp dir";
-    const getuid = options.getuid ??
-        (() => {
-            try {
-                return typeof process.getuid === "function" ? process.getuid() : undefined;
-            }
-            catch {
-                return undefined;
-            }
-        });
-    const tmpdir = typeof options.tmpdir === "function" ? options.tmpdir : getOsTmpDir;
-    const platform = options.platform ?? process.platform;
     const uid = getuid();
+    if (uid !== undefined && (!Number.isSafeInteger(uid) || uid < 0)) {
+        throw new Error("Secure temp directory user identity is invalid.");
+    }
+    if (preferredDir !== undefined) {
+        assertNoWindowsPathAlias(preferredDir, "filesystem", "preferred temp directory uses a Windows filesystem namespace alias", admissionPlatform);
+    }
     const isSecureDirForUser = (st) => {
-        if (uid === undefined) {
+        if (windows || uid === undefined)
             return true;
-        }
-        if (typeof st.uid === "number" && st.uid !== uid) {
+        const { uid: owner, mode } = st;
+        if (owner !== undefined && owner !== uid && owner !== BigInt(uid))
             return false;
-        }
-        if (typeof st.mode === "number" && (st.mode & 0o022) !== 0) {
-            return false;
-        }
-        return true;
+        if (typeof mode === "bigint")
+            return mode >= 0n && (mode & 18n) === 0n;
+        return mode === undefined || (Number.isSafeInteger(mode) && mode >= 0 && (mode & 0o022) === 0);
     };
     const fallback = () => {
         const base = tmpdir();
+        assertNoWindowsPathAlias(base, "filesystem", "system temp directory uses a Windows filesystem namespace alias", admissionPlatform);
         const suffix = uid === undefined ? fallbackPrefix : `${fallbackPrefix}-${uid}`;
         const joiner = platform === "win32" ? path.win32.join : path.join;
-        return joiner(base, suffix);
-    };
-    const isTrustedTmpDir = (st) => {
-        return st.isDirectory() && !st.isSymbolicLink() && isSecureDirForUser(st);
+        const fallbackPath = joiner(base, suffix);
+        assertNoWindowsPathAlias(fallbackPath, "filesystem", "fallback temp directory uses a Windows filesystem namespace alias", admissionPlatform);
+        return fallbackPath;
     };
     const resolveDirState = (candidatePath) => {
+        assertNoWindowsPathAlias(candidatePath, "filesystem", "temp directory uses a Windows filesystem namespace alias", admissionPlatform);
+        let candidate;
         try {
-            const candidate = lstatSync(candidatePath);
-            if (!isTrustedTmpDir(candidate)) {
-                return "invalid";
+            candidate = lstatSync(candidatePath);
+        }
+        catch (error) {
+            return { kind: isNodeErrorWithCode(error, "ENOENT") ? "missing" : "invalid", error };
+        }
+        let receipt;
+        try {
+            if (descriptor && uid !== undefined) {
+                receipt = secureTempDirectoryReceipt(candidate, uid);
+            }
+            if (receipt ? (receipt.mode & 18n) !== 0n :
+                candidate.isDirectory() !== true || candidate.isSymbolicLink() !== false || !isSecureDirForUser(candidate)) {
+                return { kind: "invalid", receipt };
             }
             accessSync(candidatePath, TMP_DIR_ACCESS_MODE);
-            return "available";
+            return { kind: "available", receipt };
         }
-        catch (err) {
-            if (isNodeErrorWithCode(err, "ENOENT")) {
-                return "missing";
-            }
-            return "invalid";
+        catch (error) {
+            return { kind: "invalid", receipt, error };
         }
     };
-    const tryRepairWritableBits = (candidatePath) => {
+    const tryRepair = (candidatePath, state, finalize = false) => {
+        assertNoWindowsPathAlias(candidatePath, "filesystem", "temp directory uses a Windows filesystem namespace alias", admissionPlatform);
+        if (!descriptor || uid === undefined || !state.receipt) {
+            return finalize ? { kind: "invalid", error: new Error("Secure temp descriptor finalization is unavailable.") } : state;
+        }
         try {
-            const st = lstatSync(candidatePath);
-            if (!st.isDirectory() || st.isSymbolicLink()) {
-                return false;
-            }
-            if (uid !== undefined && typeof st.uid === "number" && st.uid !== uid) {
-                return false;
-            }
-            if (typeof st.mode !== "number") {
-                return false;
-            }
-            if ((st.mode & 0o022) === 0) {
-                return resolveDirState(candidatePath) === "available";
-            }
-            try {
-                chmodSync(candidatePath, 0o700);
-            }
-            catch (chmodErr) {
-                if (isNodeErrorWithCode(chmodErr, "EPERM") ||
-                    isNodeErrorWithCode(chmodErr, "EACCES") ||
-                    isNodeErrorWithCode(chmodErr, "ENOENT")) {
-                    return resolveDirState(candidatePath) === "available";
-                }
-                throw chmodErr;
-            }
-            warn(`${warningPrefix} tightened permissions on temp dir: ${candidatePath}`);
-            return resolveDirState(candidatePath) === "available";
+            repairSecureTempDirectory(candidatePath, state.receipt, uid, descriptor, () => accessSync(candidatePath, TMP_DIR_ACCESS_MODE), () => warn(`${warningPrefix} tightened permissions on temp dir: ${candidatePath}`), finalize);
+            return { kind: "available" };
         }
-        catch {
-            return false;
+        catch (error) {
+            return { kind: "invalid", error };
         }
     };
     const ensureTrustedFallbackDir = () => {
         const fallbackPath = fallback();
-        const state = resolveDirState(fallbackPath);
-        if (state === "available") {
+        const entryPath = directoryEntryPath(fallbackPath, windows ? "win32" : platform);
+        let state = resolveDirState(entryPath);
+        let finalize = false;
+        if (state.kind === "available")
             return fallbackPath;
-        }
-        if (state === "invalid") {
-            if (tryRepairWritableBits(fallbackPath)) {
-                return fallbackPath;
+        if (state.kind === "missing") {
+            try {
+                if (!mkdirSync)
+                    throw new Error("Secure temp creation requires an explicit filesystem adapter.");
+                const created = mkdirSync(entryPath, { recursive: true, mode: 0o700 });
+                finalize = !windows && (suppliedMkdir !== undefined || created !== undefined);
             }
-            throw new Error(`Unsafe fallback ${unsafeFallbackLabel}: ${fallbackPath}`);
-        }
-        try {
-            mkdirSync(fallbackPath, { recursive: true, mode: 0o700 });
-            chmodSync(fallbackPath, 0o700);
-        }
-        catch {
-            throw new Error(`Unable to create fallback ${unsafeFallbackLabel}: ${fallbackPath}`);
+            catch (cause) {
+                throw new Error(`Unable to create fallback ${unsafeFallbackLabel}: ${fallbackPath}`, { cause });
+            }
+            // A concurrent mkdir winner has no implicit ownership or mode authority.
+            state = resolveDirState(entryPath);
+            if (state.kind === "available" && !finalize)
+                return fallbackPath;
         }
-        if (resolveDirState(fallbackPath) !== "available" && !tryRepairWritableBits(fallbackPath)) {
-            throw new Error(`Unsafe fallback ${unsafeFallbackLabel}: ${fallbackPath}`);
+        state = tryRepair(entryPath, state, finalize);
+        if (state.kind !== "available") {
+            throw new Error(`Unsafe fallback ${unsafeFallbackLabel}: ${fallbackPath}`, { cause: state.error });
         }
         return fallbackPath;
     };
-    if (options.skipPreferredOnWindows === true && platform === "win32") {
+    if (skipPreferredOnWindows === true && platform === "win32") {
         return ensureTrustedFallbackDir();
     }
-    if (!options.preferredDir) {
+    if (!preferredDir) {
         return ensureTrustedFallbackDir();
     }
-    const existingPreferredState = resolveDirState(options.preferredDir);
-    if (existingPreferredState === "available") {
-        return options.preferredDir;
+    const entryPath = directoryEntryPath(preferredDir, windows ? "win32" : platform);
+    const existingPreferredState = resolveDirState(entryPath);
+    if (existingPreferredState.kind === "available") {
+        return preferredDir;
     }
-    if (existingPreferredState === "invalid") {
-        if (tryRepairWritableBits(options.preferredDir)) {
-            return options.preferredDir;
+    if (existingPreferredState.kind === "invalid") {
+        if (tryRepair(entryPath, existingPreferredState).kind === "available") {
+            return preferredDir;
         }
         return ensureTrustedFallbackDir();
     }
+    let preferredAvailable = false;
     try {
-        const preferredParentDir = path.dirname(options.preferredDir);
+        const preferredParentDir = (windows ? path.win32 : path).dirname(entryPath);
         accessSync(preferredParentDir, TMP_DIR_ACCESS_MODE);
-        mkdirSync(options.preferredDir, { recursive: true, mode: 0o700 });
-        chmodSync(options.preferredDir, 0o700);
-        if (resolveDirState(options.preferredDir) !== "available" &&
-            !tryRepairWritableBits(options.preferredDir)) {
-            return ensureTrustedFallbackDir();
+        if (mkdirSync) {
+            const created = mkdirSync(entryPath, { recursive: true, mode: 0o700 });
+            const finalize = !windows && (suppliedMkdir !== undefined || created !== undefined);
+            const state = resolveDirState(entryPath);
+            preferredAvailable = (!finalize && state.kind === "available") || tryRepair(entryPath, state, finalize).kind === "available";
         }
-        return options.preferredDir;
     }
     catch {
-        return ensureTrustedFallbackDir();
+        // A failed preferred path never relaxes fallback admission.
     }
+    return preferredAvailable ? preferredDir : ensureTrustedFallbackDir();
 }

package/dist/secure-temp-repair.d.ts

@@ -0,0 +1,35 @@
+import { type BigIntStats } from "node:fs";
+type ExactDirectoryStat = Pick<BigIntStats, "dev" | "ino" | "uid" | "mode" | "isDirectory" | "isSymbolicLink">;
+/** Complete, synchronous descriptor authority for secure-temp admission and repair. */
+export type SecureTempRootDescriptorAdapter = {
+    lstatSync(path: string, options: {
+        bigint: true;
+    }): ExactDirectoryStat;
+    fstatSync(fd: number, options: {
+        bigint: true;
+    }): ExactDirectoryStat;
+    openSync(path: string, flags: number): number;
+    fchmodSync(fd: number, mode: number): void;
+    closeSync(fd: number): void;
+    constants: {
+        O_RDONLY: number;
+        O_DIRECTORY: number;
+        O_NOFOLLOW: number;
+        O_NONBLOCK: number;
+    };
+};
+export type SecureTempDirectoryReceipt = Readonly<{
+    dev: bigint;
+    ino: bigint;
+    uid: bigint;
+    mode: bigint;
+}>;
+export type SecureTempRepairAdapter = Omit<SecureTempRootDescriptorAdapter, "constants"> & {
+    flags: number;
+};
+export declare function captureSecureTempRepairAdapter(supplied: SecureTempRootDescriptorAdapter | undefined, hasLegacyFsHooks: boolean): SecureTempRepairAdapter | undefined;
+export declare function secureTempDirectoryReceipt(stat: ExactDirectoryStat, uid: number): SecureTempDirectoryReceipt;
+/** No pathname chmod, search-only descriptors, procfs, or reopening fallback. */
+export declare function repairSecureTempDirectory(candidate: string, expected: SecureTempDirectoryReceipt, uid: number, adapter: SecureTempRepairAdapter, access: () => void, repaired: () => void, finalize?: boolean): void;
+export {};
+//# sourceMappingURL=secure-temp-repair.d.ts.map

package/dist/secure-temp-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-temp-repair.d.ts","sourceRoot":"","sources":["../src/secure-temp-repair.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,KAAK,kBAAkB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,aAAa,GAAG,gBAAgB,CAAC,CAAC;AAE/G,uFAAuF;AACvF,MAAM,MAAM,+BAA+B,GAAG;IAC5C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,IAAI,CAAA;KAAE,GAAG,kBAAkB,CAAC;IACvE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,IAAI,CAAA;KAAE,GAAG,kBAAkB,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9C,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9F,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAC3G,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,+BAA+B,EAAE,WAAW,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7G,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,+BAA+B,GAAG,SAAS,EACrD,gBAAgB,EAAE,OAAO,GACxB,uBAAuB,GAAG,SAAS,CAarC;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,0BAA0B,CAS5G;AAgBD,iFAAiF;AACjF,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,0BAA0B,EACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,uBAAuB,EAChC,MAAM,EAAE,MAAM,IAAI,EAClB,QAAQ,EAAE,MAAM,IAAI,EACpB,QAAQ,UAAQ,GACf,IAAI,CAuDN"}