@openclaw/fs-safe 0.1.0

package/dist/secret-file.d.ts

@@ -0,0 +1,17 @@
+export declare const DEFAULT_SECRET_FILE_MAX_BYTES: number;
+export declare const PRIVATE_SECRET_DIR_MODE = 448;
+export declare const PRIVATE_SECRET_FILE_MODE = 384;
+export type SecretFileReadOptions = {
+    maxBytes?: number;
+    rejectSymlink?: boolean;
+};
+export declare function readSecretFileSync(filePath: string, label: string, options?: SecretFileReadOptions): string;
+export declare function tryReadSecretFileSync(filePath: string | undefined, label: string, options?: SecretFileReadOptions): string | undefined;
+export declare function writeSecretFileAtomic(params: {
+    rootDir: string;
+    filePath: string;
+    content: string | Uint8Array;
+    mode?: number;
+    dirMode?: number;
+}): Promise<void>;
+//# sourceMappingURL=secret-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAuGF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAMpB;AAoFD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDhB"}

package/dist/secret-file.js

@@ -0,0 +1,232 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { resolveHomeRelativePath } from "./home-dir.js";
+import { openPinnedFileSync } from "./pinned-open.js";
+export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
+export const PRIVATE_SECRET_DIR_MODE = 0o700;
+export const PRIVATE_SECRET_FILE_MODE = 0o600;
+function normalizeSecretReadError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function resolveUserPath(input) {
+    return resolveHomeRelativePath(input);
+}
+function readSecretFileOutcomeSync(filePath, label, options = {}) {
+    const trimmedPath = filePath.trim();
+    const resolvedPath = resolveUserPath(trimmedPath);
+    if (!resolvedPath) {
+        return { ok: false, code: "invalid-path", message: `${label} file path is empty.` };
+    }
+    const maxBytes = options.maxBytes ?? DEFAULT_SECRET_FILE_MAX_BYTES;
+    let previewStat;
+    try {
+        previewStat = fs.lstatSync(resolvedPath);
+    }
+    catch (error) {
+        const normalized = normalizeSecretReadError(error);
+        return {
+            ok: false,
+            code: error.code === "ENOENT" ? "not-found" : "invalid-path",
+            error: normalized,
+            message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
+        };
+    }
+    if (options.rejectSymlink && previewStat.isSymbolicLink()) {
+        return {
+            ok: false,
+            code: "symlink",
+            message: `${label} file at ${resolvedPath} must not be a symlink.`,
+        };
+    }
+    if (!previewStat.isFile()) {
+        return {
+            ok: false,
+            code: "not-file",
+            message: `${label} file at ${resolvedPath} must be a regular file.`,
+        };
+    }
+    if (previewStat.size > maxBytes) {
+        return {
+            ok: false,
+            code: "too-large",
+            message: `${label} file at ${resolvedPath} exceeds ${maxBytes} bytes.`,
+        };
+    }
+    const opened = openPinnedFileSync({
+        filePath: resolvedPath,
+        rejectPathSymlink: options.rejectSymlink,
+        maxBytes,
+    });
+    if (!opened.ok) {
+        const error = normalizeSecretReadError(opened.reason === "validation" ? new Error("security validation failed") : opened.error);
+        return {
+            ok: false,
+            code: opened.reason === "path" ? "not-found" : "path-mismatch",
+            error,
+            message: `Failed to read ${label} file at ${resolvedPath}: ${String(error)}`,
+        };
+    }
+    try {
+        const raw = fs.readFileSync(opened.fd, "utf8");
+        const secret = raw.trim();
+        if (!secret) {
+            return {
+                ok: false,
+                code: "invalid-path",
+                message: `${label} file at ${resolvedPath} is empty.`,
+            };
+        }
+        return { ok: true, secret };
+    }
+    catch (error) {
+        const normalized = normalizeSecretReadError(error);
+        return {
+            ok: false,
+            code: "invalid-path",
+            error: normalized,
+            message: `Failed to read ${label} file at ${resolvedPath}: ${String(normalized)}`,
+        };
+    }
+    finally {
+        fs.closeSync(opened.fd);
+    }
+}
+export function readSecretFileSync(filePath, label, options = {}) {
+    const result = readSecretFileOutcomeSync(filePath, label, options);
+    if (result.ok) {
+        return result.secret;
+    }
+    throw new FsSafeError(result.code, result.message, {
+        cause: result.error,
+    });
+}
+export function tryReadSecretFileSync(filePath, label, options = {}) {
+    if (!filePath?.trim()) {
+        return undefined;
+    }
+    const result = readSecretFileOutcomeSync(filePath, label, options);
+    return result.ok ? result.secret : undefined;
+}
+function assertPathWithinRoot(rootDir, targetPath) {
+    const relative = path.relative(rootDir, targetPath);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`Private secret path must stay under ${rootDir}.`);
+    }
+}
+function assertRealPathWithinRoot(rootDir, targetPath) {
+    const relative = path.relative(rootDir, targetPath);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`Private secret path must stay under ${rootDir}.`);
+    }
+}
+async function enforcePrivatePathMode(resolvedPath, expectedMode, kind) {
+    if (process.platform === "win32") {
+        return;
+    }
+    await fsp.chmod(resolvedPath, expectedMode);
+    const stat = await fsp.stat(resolvedPath);
+    const actualMode = stat.mode & 0o777;
+    if (actualMode !== expectedMode) {
+        throw new Error(`Private secret ${kind} ${resolvedPath} has insecure permissions ${actualMode.toString(8)}.`);
+    }
+}
+async function ensurePrivateDirectory(rootDir, targetDir, mode) {
+    const resolvedRoot = path.resolve(rootDir);
+    const resolvedTarget = path.resolve(targetDir);
+    if (resolvedTarget === resolvedRoot) {
+        await fsp.mkdir(resolvedRoot, { recursive: true, mode });
+        const rootStat = await fsp.lstat(resolvedRoot);
+        if (rootStat.isSymbolicLink()) {
+            throw new Error(`Private secret root ${resolvedRoot} must not be a symlink.`);
+        }
+        if (!rootStat.isDirectory()) {
+            throw new Error(`Private secret root ${resolvedRoot} must be a directory.`);
+        }
+        await enforcePrivatePathMode(resolvedRoot, mode, "directory");
+        return;
+    }
+    assertPathWithinRoot(resolvedRoot, resolvedTarget);
+    await ensurePrivateDirectory(resolvedRoot, resolvedRoot, mode);
+    const resolvedRootReal = await fsp.realpath(resolvedRoot);
+    let current = resolvedRoot;
+    for (const segment of path
+        .relative(resolvedRoot, resolvedTarget)
+        .split(path.sep)
+        .filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            const stat = await fsp.lstat(current);
+            if (stat.isSymbolicLink()) {
+                throw new Error(`Private secret directory component ${current} must not be a symlink.`);
+            }
+            if (!stat.isDirectory()) {
+                throw new Error(`Private secret directory component ${current} must be a directory.`);
+            }
+        }
+        catch (error) {
+            if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
+                throw error;
+            }
+            await fsp.mkdir(current, { mode });
+        }
+        const currentReal = await fsp.realpath(current);
+        assertRealPathWithinRoot(resolvedRootReal, currentReal);
+        await enforcePrivatePathMode(currentReal, mode, "directory");
+    }
+}
+export async function writeSecretFileAtomic(params) {
+    const mode = params.mode ?? PRIVATE_SECRET_FILE_MODE;
+    const dirMode = params.dirMode ?? PRIVATE_SECRET_DIR_MODE;
+    const resolvedRoot = path.resolve(params.rootDir);
+    const resolvedFile = path.resolve(params.filePath);
+    assertPathWithinRoot(resolvedRoot, resolvedFile);
+    const intendedParentDir = path.dirname(resolvedFile);
+    await ensurePrivateDirectory(resolvedRoot, intendedParentDir, dirMode);
+    const resolvedRootReal = await fsp.realpath(resolvedRoot);
+    const parentDir = await fsp.realpath(intendedParentDir);
+    assertRealPathWithinRoot(resolvedRootReal, parentDir);
+    const fileName = path.basename(resolvedFile);
+    const finalFilePath = path.join(parentDir, fileName);
+    try {
+        const stat = await fsp.lstat(finalFilePath);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Private secret file ${finalFilePath} must not be a symlink.`);
+        }
+        if (!stat.isFile()) {
+            throw new Error(`Private secret file ${finalFilePath} must be a regular file.`);
+        }
+    }
+    catch (error) {
+        if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    const tempPath = path.join(parentDir, `.tmp-${process.pid}-${Date.now()}-${randomBytes(6).toString("hex")}`);
+    let createdTemp = false;
+    try {
+        const handle = await fsp.open(tempPath, "wx", mode);
+        createdTemp = true;
+        try {
+            await handle.writeFile(params.content);
+        }
+        finally {
+            await handle.close();
+        }
+        await enforcePrivatePathMode(tempPath, mode, "file");
+        const refreshedParentReal = await fsp.realpath(intendedParentDir);
+        if (refreshedParentReal !== parentDir) {
+            throw new Error(`Private secret parent directory changed during write for ${finalFilePath}.`);
+        }
+        await fsp.rename(tempPath, finalFilePath);
+        createdTemp = false;
+        await enforcePrivatePathMode(finalFilePath, mode, "file");
+    }
+    finally {
+        if (createdTemp) {
+            await fsp.unlink(tempPath).catch(() => undefined);
+        }
+    }
+}

package/dist/secret.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_SECRET_FILE_MAX_BYTES, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, type SecretFileReadOptions, } from "./secret-file.js";
+//# sourceMappingURL=secret.d.ts.map

package/dist/secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,kBAAkB,CAAC"}

package/dist/secret.js

@@ -0,0 +1 @@
+export { DEFAULT_SECRET_FILE_MAX_BYTES, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, } from "./secret-file.js";

package/dist/secure-file.d.ts

@@ -0,0 +1,32 @@
+import type { Stats } from "node:fs";
+import { type PermissionCheck, type PermissionCheckOptions } from "./permissions.js";
+export type SecureFileReadOptions = {
+    filePath: string;
+    label?: string;
+    trust?: SecureFileTrustOptions;
+    permissions?: SecureFilePermissionOptions;
+    inject?: SecureFileInjectOptions;
+    io?: SecureFileIoOptions;
+};
+export type SecureFileTrustOptions = {
+    trustedDirs?: string[];
+    allowSymlink?: boolean;
+    allowNetworkPath?: boolean;
+};
+export type SecureFilePermissionOptions = {
+    allowInsecure?: boolean;
+    allowReadableByOthers?: boolean;
+};
+export type SecureFileInjectOptions = PermissionCheckOptions;
+export type SecureFileIoOptions = {
+    maxBytes?: number;
+    timeoutMs?: number;
+};
+export type SecureFileReadResult = {
+    buffer: Buffer;
+    realPath: string;
+    stat: Stats;
+    permissions?: PermissionCheck;
+};
+export declare function readSecureFile(options: SecureFileReadOptions): Promise<SecureFileReadResult>;
+//# sourceMappingURL=secure-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAUrC,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;AAkKF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAa/B"}

package/dist/secure-file.js

@@ -0,0 +1,163 @@
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { isWindowsDriveLetterPath, isWindowsNetworkPath } from "./local-file-access.js";
+import { isPathInside, isSymlinkOpenError } from "./path.js";
+import { inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, } from "./permissions.js";
+const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
+const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
+function isAbsolutePathname(value) {
+    return path.isAbsolute(value) || isWindowsDriveLetterPath(value, "win32") || isWindowsNetworkPath(value, "win32");
+}
+function label(options) {
+    return options.label ?? "Secure file";
+}
+async function openSecureHandle(options) {
+    if (isWindowsNetworkPath(options.filePath, "win32") && !options.trust?.allowNetworkPath) {
+        throw new FsSafeError("invalid-path", `${label(options)} must be a local absolute path.`);
+    }
+    if (!isAbsolutePathname(options.filePath)) {
+        throw new FsSafeError("invalid-path", `${label(options)} must be an absolute path.`);
+    }
+    const preStat = await fs.lstat(options.filePath).catch((err) => {
+        throw new FsSafeError("not-found", `${label(options)} is not readable: ${options.filePath}`, {
+            cause: err,
+        });
+    });
+    if (preStat.isDirectory()) {
+        throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
+    }
+    if (preStat.isSymbolicLink() && !options.trust?.allowSymlink) {
+        throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+    }
+    let handle;
+    try {
+        handle = await fs.open(options.filePath, options.trust?.allowSymlink ? fsConstants.O_RDONLY : OPEN_READ_FLAGS);
+    }
+    catch (err) {
+        if (isSymlinkOpenError(err)) {
+            throw new FsSafeError("symlink", `${label(options)} symlink open blocked`, { cause: err });
+        }
+        throw err;
+    }
+    try {
+        const openedStat = await handle.stat();
+        if (!openedStat.isFile()) {
+            throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
+        }
+        const pathStat = options.trust?.allowSymlink
+            ? await fs.stat(options.filePath)
+            : await fs.lstat(options.filePath);
+        if (!options.trust?.allowSymlink && pathStat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+        }
+        if (!sameFileIdentity(pathStat, openedStat)) {
+            throw new FsSafeError("path-mismatch", `${label(options)} changed during open.`);
+        }
+        const realPath = await fs.realpath(options.filePath);
+        const realStat = await fs.stat(realPath);
+        if (!sameFileIdentity(realStat, openedStat)) {
+            throw new FsSafeError("path-mismatch", `${label(options)} real path changed during open.`);
+        }
+        if (options.io?.maxBytes !== undefined && openedStat.size > options.io.maxBytes) {
+            throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${options.io.maxBytes}).`);
+        }
+        return { handle, pathStat: openedStat, realPath };
+    }
+    catch (err) {
+        await handle.close().catch(() => undefined);
+        throw err;
+    }
+}
+async function assertTrustedDirs(options, realPath) {
+    if (!options.trust?.trustedDirs || options.trust.trustedDirs.length === 0) {
+        return;
+    }
+    const trusted = await Promise.all(options.trust.trustedDirs.map(async (dir) => {
+        const resolved = path.resolve(dir);
+        return await fs.realpath(resolved).catch(() => resolved);
+    }));
+    if (!trusted.some((dir) => isPathInside(dir, realPath))) {
+        throw new FsSafeError("outside-workspace", `${label(options)} is outside trustedDirs: ${realPath}`);
+    }
+}
+function inspectOpenedPermissions(stat, platform) {
+    const bits = modeBits(typeof stat.mode === "number" ? stat.mode : null);
+    return {
+        ok: true,
+        isSymlink: false,
+        isDir: stat.isDirectory(),
+        mode: typeof stat.mode === "number" ? stat.mode : null,
+        bits,
+        source: platform === "win32" ? "unknown" : "posix",
+        worldWritable: isWorldWritable(bits),
+        groupWritable: isGroupWritable(bits),
+        worldReadable: isWorldReadable(bits),
+        groupReadable: isGroupReadable(bits),
+    };
+}
+async function assertSecurePermissions(options, stat, realPath) {
+    if (options.permissions?.allowInsecure) {
+        return undefined;
+    }
+    const platform = options.inject?.platform ?? process.platform;
+    const permissions = platform === "win32"
+        ? await inspectPathPermissions(realPath, options.inject)
+        : inspectOpenedPermissions(stat, platform);
+    if (!permissions.ok) {
+        throw new FsSafeError("permission-unverified", `${label(options)} permissions could not be verified: ${realPath}`);
+    }
+    if (platform === "win32" && permissions.source === "unknown") {
+        throw new FsSafeError("permission-unverified", `${label(options)} ACL verification unavailable on Windows for ${realPath}.`);
+    }
+    const writableByOthers = permissions.worldWritable || permissions.groupWritable;
+    const readableByOthers = permissions.worldReadable || permissions.groupReadable;
+    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 (stat.uid !== uid) {
+            throw new FsSafeError("not-owned", `${label(options)} must be owned by the current user (uid=${uid}): ${realPath}`);
+        }
+    }
+    return permissions;
+}
+async function readHandleWithTimeout(handle, timeoutMs) {
+    if (timeoutMs === undefined || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return await handle.readFile();
+    }
+    let timeout;
+    try {
+        return await Promise.race([
+            handle.readFile(),
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => {
+                    void handle.close().catch(() => undefined);
+                    reject(new FsSafeError("timeout", `secure file read timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+export async function readSecureFile(options) {
+    const opened = await openSecureHandle(options);
+    try {
+        await assertTrustedDirs(options, opened.realPath);
+        const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath);
+        const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs);
+        if (options.io?.maxBytes !== undefined && buffer.byteLength > options.io.maxBytes) {
+            throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${options.io.maxBytes}).`);
+        }
+        return { buffer, realPath: opened.realPath, stat: opened.pathStat, permissions };
+    }
+    finally {
+        await opened.handle.close().catch(() => undefined);
+    }
+}

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

@@ -0,0 +1,27 @@
+type SecureDirStat = {
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    mode?: number;
+    uid?: number;
+};
+export type ResolveSecureTempRootOptions = {
+    accessSync?: (path: string, mode?: number) => void;
+    chmodSync?: (path: string, mode: number) => void;
+    fallbackPrefix: string;
+    getuid?: () => number | undefined;
+    lstatSync?: (path: string) => SecureDirStat;
+    mkdirSync?: (path: string, opts: {
+        recursive: boolean;
+        mode?: number;
+    }) => void;
+    platform?: NodeJS.Platform;
+    preferredDir?: string;
+    skipPreferredOnWindows?: boolean;
+    tmpdir?: () => string;
+    unsafeFallbackLabel?: string;
+    warn?: (message: string) => void;
+    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

@@ -0,0 +1 @@
+{"version":3,"file":"secure-temp-dir.d.ts","sourceRoot":"","sources":["../src/secure-temp-dir.ts"],"names":[],"mappings":"AAMA,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,CA0JnF"}

package/dist/secure-temp-dir.js

@@ -0,0 +1,155 @@
+import fs from "node:fs";
+import { tmpdir as getOsTmpDir } from "node:os";
+import path from "node:path";
+function isNodeErrorWithCode(err, code) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        err.code === code);
+}
+export function resolveSecureTempRoot(options) {
+    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 ?? fs.mkdirSync;
+    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();
+    const isSecureDirForUser = (st) => {
+        if (uid === undefined) {
+            return true;
+        }
+        if (typeof st.uid === "number" && st.uid !== uid) {
+            return false;
+        }
+        if (typeof st.mode === "number" && (st.mode & 0o022) !== 0) {
+            return false;
+        }
+        return true;
+    };
+    const fallback = () => {
+        const base = tmpdir();
+        const suffix = uid === undefined ? options.fallbackPrefix : `${options.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 resolveDirState = (candidatePath) => {
+        try {
+            const candidate = lstatSync(candidatePath);
+            if (!isTrustedTmpDir(candidate)) {
+                return "invalid";
+            }
+            accessSync(candidatePath, TMP_DIR_ACCESS_MODE);
+            return "available";
+        }
+        catch (err) {
+            if (isNodeErrorWithCode(err, "ENOENT")) {
+                return "missing";
+            }
+            return "invalid";
+        }
+    };
+    const tryRepairWritableBits = (candidatePath) => {
+        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";
+        }
+        catch {
+            return false;
+        }
+    };
+    const ensureTrustedFallbackDir = () => {
+        const fallbackPath = fallback();
+        const state = resolveDirState(fallbackPath);
+        if (state === "available") {
+            return fallbackPath;
+        }
+        if (state === "invalid") {
+            if (tryRepairWritableBits(fallbackPath)) {
+                return fallbackPath;
+            }
+            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}`);
+        }
+        if (resolveDirState(fallbackPath) !== "available" && !tryRepairWritableBits(fallbackPath)) {
+            throw new Error(`Unsafe fallback ${unsafeFallbackLabel}: ${fallbackPath}`);
+        }
+        return fallbackPath;
+    };
+    if (options.skipPreferredOnWindows === true && platform === "win32") {
+        return ensureTrustedFallbackDir();
+    }
+    if (!options.preferredDir) {
+        return ensureTrustedFallbackDir();
+    }
+    const existingPreferredState = resolveDirState(options.preferredDir);
+    if (existingPreferredState === "available") {
+        return options.preferredDir;
+    }
+    if (existingPreferredState === "invalid") {
+        if (tryRepairWritableBits(options.preferredDir)) {
+            return options.preferredDir;
+        }
+        return ensureTrustedFallbackDir();
+    }
+    try {
+        const preferredParentDir = path.dirname(options.preferredDir);
+        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();
+        }
+        return options.preferredDir;
+    }
+    catch {
+        return ensureTrustedFallbackDir();
+    }
+}

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

@@ -0,0 +1,25 @@
+export type SecureTempWorkspaceOptions = {
+    rootDir: string;
+    prefix: string;
+    dirMode?: number;
+    fileMode?: number;
+};
+export type SecureTempWorkspace = {
+    dir: string;
+    path(fileName: string): string;
+    writePrivate(fileName: string, data: string | Uint8Array): Promise<string>;
+    read(fileName: string): Promise<Buffer>;
+    cleanup(): Promise<void>;
+};
+export type SecureTempWorkspaceSync = {
+    dir: string;
+    path(fileName: string): string;
+    writePrivate(fileName: string, data: string | Uint8Array): string;
+    read(fileName: string): Buffer;
+    cleanup(): void;
+};
+export declare function createSecureTempWorkspace(options: SecureTempWorkspaceOptions): Promise<SecureTempWorkspace>;
+export declare function withSecureTempWorkspace<T>(options: SecureTempWorkspaceOptions, run: (workspace: SecureTempWorkspace) => Promise<T>): Promise<T>;
+export declare function createSecureTempWorkspaceSync(options: SecureTempWorkspaceOptions): SecureTempWorkspaceSync;
+export declare function withSecureTempWorkspaceSync<T>(options: SecureTempWorkspaceOptions, run: (workspace: SecureTempWorkspaceSync) => T): T;
+//# sourceMappingURL=secure-temp-workspace.d.ts.map