@openclaw/fs-safe 0.1.0

package/dist/permissions.js

@@ -0,0 +1,435 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+const execFileAsync = promisify(execFile);
+const INHERIT_FLAGS = new Set(["I", "OI", "CI", "IO", "NP"]);
+const WORLD_PRINCIPALS = new Set([
+    "everyone",
+    "users",
+    "builtin\\users",
+    "authenticated users",
+    "nt authority\\authenticated users",
+]);
+const TRUSTED_BASE = new Set([
+    "nt authority\\system",
+    "system",
+    "builtin\\administrators",
+    "creator owner",
+    "autorite nt\\système",
+    "nt-autorität\\system",
+    "autoridad nt\\system",
+    "autoridade nt\\system",
+]);
+const WORLD_SUFFIXES = ["\\users", "\\authenticated users"];
+const TRUSTED_SUFFIXES = ["\\administrators", "\\system", "\\système"];
+const SID_RE = /^\*?s-\d+-\d+(-\d+)+$/i;
+const TRUSTED_SIDS = new Set([
+    "s-1-5-18",
+    "s-1-5-32-544",
+    "s-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464",
+]);
+const WORLD_SIDS = new Set(["s-1-1-0", "s-1-5-11", "s-1-5-32-545"]);
+const STATUS_PREFIXES = [
+    "successfully processed",
+    "processed",
+    "failed processing",
+    "no mapping between account names",
+];
+const normalize = (value) => normalizeLowercaseStringOrEmpty(value);
+const defaultWindowsUserInfo = () => os.userInfo();
+function defaultPermissionExec(command, args) {
+    return execFileAsync(command, args, {
+        encoding: "utf8",
+        windowsHide: true,
+        maxBuffer: 1024 * 1024,
+    });
+}
+export async function safeStat(targetPath) {
+    try {
+        const lst = await fs.lstat(targetPath);
+        return {
+            ok: true,
+            isSymlink: lst.isSymbolicLink(),
+            isDir: lst.isDirectory(),
+            mode: typeof lst.mode === "number" ? lst.mode : null,
+            uid: typeof lst.uid === "number" ? lst.uid : null,
+            gid: typeof lst.gid === "number" ? lst.gid : null,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            isSymlink: false,
+            isDir: false,
+            mode: null,
+            uid: null,
+            gid: null,
+            error: String(err),
+        };
+    }
+}
+export async function inspectPathPermissions(targetPath, opts) {
+    const st = await safeStat(targetPath);
+    if (!st.ok) {
+        return {
+            ok: false,
+            isSymlink: false,
+            isDir: false,
+            mode: null,
+            bits: null,
+            source: "unknown",
+            worldWritable: false,
+            groupWritable: false,
+            worldReadable: false,
+            groupReadable: false,
+            error: st.error,
+        };
+    }
+    let effectiveMode = st.mode;
+    let effectiveIsDir = st.isDir;
+    if (st.isSymlink) {
+        try {
+            const target = await fs.stat(targetPath);
+            effectiveMode = typeof target.mode === "number" ? target.mode : st.mode;
+            effectiveIsDir = target.isDirectory();
+        }
+        catch {
+            // Keep lstat metadata when the symlink target cannot be inspected.
+        }
+    }
+    const bits = modeBits(effectiveMode);
+    const platform = opts?.platform ?? process.platform;
+    if (platform === "win32") {
+        const acl = await inspectWindowsAcl(targetPath, { env: opts?.env, exec: opts?.exec });
+        if (!acl.ok) {
+            return {
+                ok: true,
+                isSymlink: st.isSymlink,
+                isDir: effectiveIsDir,
+                mode: effectiveMode,
+                bits,
+                source: "unknown",
+                worldWritable: false,
+                groupWritable: false,
+                worldReadable: false,
+                groupReadable: false,
+                error: acl.error,
+            };
+        }
+        return {
+            ok: true,
+            isSymlink: st.isSymlink,
+            isDir: effectiveIsDir,
+            mode: effectiveMode,
+            bits,
+            source: "windows-acl",
+            worldWritable: acl.untrustedWorld.some((entry) => entry.canWrite),
+            groupWritable: acl.untrustedGroup.some((entry) => entry.canWrite),
+            worldReadable: acl.untrustedWorld.some((entry) => entry.canRead),
+            groupReadable: acl.untrustedGroup.some((entry) => entry.canRead),
+            aclSummary: formatWindowsAclSummary(acl),
+        };
+    }
+    return {
+        ok: true,
+        isSymlink: st.isSymlink,
+        isDir: effectiveIsDir,
+        mode: effectiveMode,
+        bits,
+        source: "posix",
+        worldWritable: isWorldWritable(bits),
+        groupWritable: isGroupWritable(bits),
+        worldReadable: isWorldReadable(bits),
+        groupReadable: isGroupReadable(bits),
+    };
+}
+export function formatPermissionDetail(targetPath, perms) {
+    if (perms.source === "windows-acl") {
+        return `${targetPath} acl=${perms.aclSummary ?? "unknown"}`;
+    }
+    return `${targetPath} mode=${formatOctal(perms.bits)}`;
+}
+export function formatPermissionRemediation(params) {
+    if (params.perms.source === "windows-acl") {
+        return formatIcaclsResetCommand(params.targetPath, {
+            isDir: params.isDir,
+            env: params.env,
+        });
+    }
+    return `chmod ${params.posixMode.toString(8).padStart(3, "0")} ${params.targetPath}`;
+}
+export function modeBits(mode) {
+    return mode == null ? null : mode & 0o777;
+}
+export function formatOctal(bits) {
+    return bits == null ? "unknown" : bits.toString(8).padStart(3, "0");
+}
+export function isWorldWritable(bits) {
+    return bits != null && (bits & 0o002) !== 0;
+}
+export function isGroupWritable(bits) {
+    return bits != null && (bits & 0o020) !== 0;
+}
+export function isWorldReadable(bits) {
+    return bits != null && (bits & 0o004) !== 0;
+}
+export function isGroupReadable(bits) {
+    return bits != null && (bits & 0o040) !== 0;
+}
+function normalizeSid(value) {
+    const normalized = normalize(value);
+    return normalized.startsWith("*") ? normalized.slice(1) : normalized;
+}
+export function resolveWindowsUserPrincipal(env, userInfo = defaultWindowsUserInfo) {
+    const username = env?.USERNAME?.trim() || userInfo().username?.trim();
+    if (!username) {
+        return null;
+    }
+    const domain = env?.USERDOMAIN?.trim();
+    return domain ? `${domain}\\${username}` : username;
+}
+function buildTrustedPrincipals(env) {
+    const trusted = new Set(TRUSTED_BASE);
+    const principal = resolveWindowsUserPrincipal(env);
+    if (principal) {
+        trusted.add(normalize(principal));
+        const userOnly = principal.split("\\").at(-1);
+        if (userOnly) {
+            trusted.add(normalize(userOnly));
+        }
+    }
+    const userSid = normalizeSid(env?.USERSID ?? "");
+    if (userSid && SID_RE.test(userSid) && !WORLD_SIDS.has(userSid)) {
+        trusted.add(userSid);
+    }
+    return trusted;
+}
+function getEnvValueCaseInsensitive(env, name) {
+    const direct = env[name];
+    if (direct !== undefined) {
+        return direct;
+    }
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(env)) {
+        if (key.toLowerCase() === lower) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function normalizeWindowsInstallRoot(value) {
+    const trimmed = value?.trim();
+    if (!trimmed || !path.win32.isAbsolute(trimmed)) {
+        return null;
+    }
+    return trimmed.replace(/[\\/]+$/, "");
+}
+function resolveWindowsSystemRoot(env) {
+    const source = env ?? process.env;
+    return (normalizeWindowsInstallRoot(getEnvValueCaseInsensitive(source, "SystemRoot")) ??
+        normalizeWindowsInstallRoot(getEnvValueCaseInsensitive(source, "WINDIR")) ??
+        "C:\\Windows");
+}
+function resolveWindowsSystemCommand(command, env) {
+    const root = resolveWindowsSystemRoot(env);
+    return path.win32.join(root, "System32", command);
+}
+function classifyPrincipal(principal, trustedPrincipals) {
+    const normalized = normalize(principal);
+    if (SID_RE.test(normalized)) {
+        const sid = normalizeSid(normalized);
+        if (WORLD_SIDS.has(sid))
+            return "world";
+        if (TRUSTED_SIDS.has(sid) || trustedPrincipals.has(sid))
+            return "trusted";
+        return "group";
+    }
+    if (trustedPrincipals.has(normalized) ||
+        TRUSTED_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
+        return "trusted";
+    }
+    if (WORLD_PRINCIPALS.has(normalized) ||
+        WORLD_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
+        return "world";
+    }
+    const stripped = normalized.normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+    if (stripped !== normalized &&
+        (TRUSTED_BASE.has(stripped) ||
+            TRUSTED_SUFFIXES.some((suffix) => {
+                const strippedSuffix = suffix.normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+                return stripped.endsWith(strippedSuffix);
+            }))) {
+        return "trusted";
+    }
+    return "group";
+}
+function rightsFromTokens(tokens) {
+    const upper = tokens.join("").toUpperCase();
+    return {
+        canWrite: upper.includes("F") || upper.includes("M") || upper.includes("W") || upper.includes("D"),
+        canRead: upper.includes("F") || upper.includes("M") || upper.includes("R"),
+    };
+}
+function stripTargetPrefix(params) {
+    if (params.lowerLine.startsWith(params.lowerTarget)) {
+        return params.trimmedLine.slice(params.normalizedTarget.length).trim();
+    }
+    if (params.lowerLine.startsWith(params.quotedLower)) {
+        return params.trimmedLine.slice(params.quotedTarget.length).trim();
+    }
+    return params.trimmedLine;
+}
+function parseAceEntry(entry) {
+    if (!entry.includes("("))
+        return null;
+    const idx = entry.indexOf(":");
+    if (idx === -1)
+        return null;
+    const principal = entry.slice(0, idx).trim();
+    const rawRights = entry.slice(idx + 1).trim();
+    const tokens = rawRights
+        .match(/\(([^)]+)\)/g)
+        ?.map((token) => token.slice(1, -1).trim())
+        .filter(Boolean) ?? [];
+    if (tokens.some((token) => token.toUpperCase() === "DENY"))
+        return null;
+    const rights = tokens.filter((token) => !INHERIT_FLAGS.has(token.toUpperCase()));
+    if (rights.length === 0)
+        return null;
+    return { principal, rights, rawRights, ...rightsFromTokens(rights) };
+}
+export function parseIcaclsOutput(output, targetPath) {
+    const entries = [];
+    const normalizedTarget = targetPath.trim();
+    const lowerTarget = normalizedTarget.toLowerCase();
+    const quotedTarget = `"${normalizedTarget}"`;
+    const quotedLower = quotedTarget.toLowerCase();
+    for (const rawLine of output.split(/\r?\n/)) {
+        const line = rawLine.trimEnd();
+        if (!line.trim())
+            continue;
+        const trimmed = line.trim();
+        const lower = trimmed.toLowerCase();
+        if (STATUS_PREFIXES.some((prefix) => lower.startsWith(prefix)))
+            continue;
+        const parsed = parseAceEntry(stripTargetPrefix({
+            trimmedLine: trimmed,
+            lowerLine: lower,
+            normalizedTarget,
+            lowerTarget,
+            quotedTarget,
+            quotedLower,
+        }));
+        if (parsed)
+            entries.push(parsed);
+    }
+    return entries;
+}
+export function summarizeWindowsAcl(entries, env) {
+    const trustedPrincipals = buildTrustedPrincipals(env);
+    const trusted = [];
+    const untrustedWorld = [];
+    const untrustedGroup = [];
+    for (const entry of entries) {
+        const classification = classifyPrincipal(entry.principal, trustedPrincipals);
+        if (classification === "trusted")
+            trusted.push(entry);
+        else if (classification === "world")
+            untrustedWorld.push(entry);
+        else
+            untrustedGroup.push(entry);
+    }
+    return { trusted, untrustedWorld, untrustedGroup };
+}
+async function resolveCurrentUserSid(exec, env) {
+    try {
+        const { stdout, stderr } = await exec(resolveWindowsSystemCommand("whoami.exe", env), [
+            "/user",
+            "/fo",
+            "csv",
+            "/nh",
+        ]);
+        const match = `${stdout}\n${stderr}`.match(/\*?S-\d+-\d+(?:-\d+)+/i);
+        return match ? normalizeSid(match[0]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function inspectWindowsAcl(targetPath, opts) {
+    const exec = opts?.exec ?? defaultPermissionExec;
+    try {
+        const { stdout, stderr } = await exec(resolveWindowsSystemCommand("icacls.exe", opts?.env), [
+            targetPath,
+            "/sid",
+        ]);
+        const entries = parseIcaclsOutput(`${stdout}\n${stderr}`.trim(), targetPath);
+        let effectiveEnv = opts?.env;
+        let { trusted, untrustedWorld, untrustedGroup } = summarizeWindowsAcl(entries, effectiveEnv);
+        const needsUserSidResolution = !effectiveEnv?.USERSID &&
+            untrustedGroup.some((entry) => SID_RE.test(normalize(entry.principal)));
+        if (needsUserSidResolution) {
+            const currentUserSid = await resolveCurrentUserSid(exec, effectiveEnv);
+            if (currentUserSid) {
+                effectiveEnv = { ...effectiveEnv, USERSID: currentUserSid };
+                ({ trusted, untrustedWorld, untrustedGroup } = summarizeWindowsAcl(entries, effectiveEnv));
+            }
+        }
+        return { ok: true, entries, trusted, untrustedWorld, untrustedGroup };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            entries: [],
+            trusted: [],
+            untrustedWorld: [],
+            untrustedGroup: [],
+            error: String(err),
+        };
+    }
+}
+export function formatWindowsAclSummary(summary) {
+    if (!summary.ok)
+        return "unknown";
+    const untrusted = [...summary.untrustedWorld, ...summary.untrustedGroup];
+    return untrusted.length === 0
+        ? "trusted-only"
+        : untrusted.map((entry) => `${entry.principal}:${entry.rawRights}`).join(", ");
+}
+export function formatIcaclsResetCommand(targetPath, opts) {
+    const command = resolveWindowsSystemCommand("icacls.exe", opts.env);
+    const user = resolveWindowsUserPrincipal(opts.env, opts.userInfo) ?? "%USERNAME%";
+    const grant = opts.isDir ? "(OI)(CI)F" : "F";
+    return [
+        command,
+        `"${targetPath}"`,
+        "/inheritance:r",
+        "/grant:r",
+        `"${user}:${grant}"`,
+        "/grant:r",
+        `"*S-1-5-18:${grant}"`,
+    ].join(" ");
+}
+export function createIcaclsResetCommand(targetPath, opts) {
+    const user = resolveWindowsUserPrincipal(opts.env, opts.userInfo);
+    if (!user) {
+        return null;
+    }
+    const grant = opts.isDir ? "(OI)(CI)F" : "F";
+    const args = [
+        targetPath,
+        "/inheritance:r",
+        "/grant:r",
+        `${user}:${grant}`,
+        "/grant:r",
+        `*S-1-5-18:${grant}`,
+    ];
+    return {
+        command: resolveWindowsSystemCommand("icacls.exe", opts.env),
+        args,
+        display: formatIcaclsResetCommand(targetPath, opts),
+    };
+}

package/dist/pinned-helper.d.ts

@@ -0,0 +1,9 @@
+import type { DirEntry, PathStat } from "./types.js";
+import { isPinnedHelperUnavailable } from "./pinned-python.js";
+type HelperOperation = "stat" | "readdir" | "mkdirp" | "remove" | "rename";
+export { isPinnedHelperUnavailable };
+export declare function runPinnedHelper<T>(operation: HelperOperation, rootDir: string, payload: Record<string, unknown>): Promise<T>;
+export declare function helperStat(rootDir: string, relativePath: string): Promise<PathStat>;
+export declare function helperReaddir(rootDir: string, relativePath: string, withFileTypes: false): Promise<string[]>;
+export declare function helperReaddir(rootDir: string, relativePath: string, withFileTypes: true): Promise<DirEntry[]>;
+//# sourceMappingURL=pinned-helper.d.ts.map

package/dist/pinned-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-helper.d.ts","sourceRoot":"","sources":["../src/pinned-helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EACL,yBAAyB,EAG1B,MAAM,oBAAoB,CAAC;AAE5B,KAAK,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3E,OAAO,EAAE,yBAAyB,EAAE,CAAC;AAErC,wBAAsB,eAAe,CAAC,CAAC,EACrC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEzF;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,KAAK,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AACrB,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,IAAI,GAClB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC"}

package/dist/pinned-helper.js

@@ -0,0 +1,19 @@
+import { isPinnedHelperUnavailable, runPinnedPythonOperation, validatePinnedOperationPayload, } from "./pinned-python.js";
+export { isPinnedHelperUnavailable };
+export async function runPinnedHelper(operation, rootDir, payload) {
+    validatePinnedOperationPayload(payload);
+    return await runPinnedPythonOperation({
+        operation,
+        rootPath: rootDir,
+        payload,
+    });
+}
+export async function helperStat(rootDir, relativePath) {
+    return await runPinnedHelper("stat", rootDir, { relativePath });
+}
+export async function helperReaddir(rootDir, relativePath, withFileTypes) {
+    return await runPinnedHelper("readdir", rootDir, {
+        relativePath,
+        withFileTypes,
+    });
+}

package/dist/pinned-open.d.ts

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+export type PinnedOpenSyncFailureReason = "path" | "validation" | "io";
+export type PinnedOpenSyncResult = {
+    ok: true;
+    path: string;
+    fd: number;
+    stat: fs.Stats;
+} | {
+    ok: false;
+    reason: PinnedOpenSyncFailureReason;
+    error?: unknown;
+};
+export type PinnedOpenSyncAllowedType = "file" | "directory";
+export type PinnedOpenSyncFs = Pick<typeof fs, "constants" | "lstatSync" | "realpathSync" | "openSync" | "fstatSync" | "closeSync">;
+export declare function openPinnedFileSync(params: {
+    filePath: string;
+    resolvedPath?: string;
+    rejectPathSymlink?: boolean;
+    rejectHardlinks?: boolean;
+    maxBytes?: number;
+    allowedType?: PinnedOpenSyncAllowedType;
+    ioFs?: PinnedOpenSyncFs;
+}): PinnedOpenSyncResult;
+//# sourceMappingURL=pinned-open.d.ts.map

package/dist/pinned-open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-open.d.ts","sourceRoot":"","sources":["../src/pinned-open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAGzB,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;AAEvE,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,2BAA2B,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAExE,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,WAAW,CAAC;AAE7D,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,OAAO,EAAE,EACT,WAAW,GAAG,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CACpF,CAAC;AAYF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB,GAAG,oBAAoB,CA2DvB"}

package/dist/pinned-open.js

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import { sameFileIdentity as hasSameFileIdentity } from "./file-identity.js";
+function isExpectedPathError(error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
+}
+function sameFileIdentity(left, right) {
+    return hasSameFileIdentity(left, right);
+}
+export function openPinnedFileSync(params) {
+    const ioFs = params.ioFs ?? fs;
+    const allowedType = params.allowedType ?? "file";
+    const openReadFlags = ioFs.constants.O_RDONLY |
+        (typeof ioFs.constants.O_NOFOLLOW === "number" ? ioFs.constants.O_NOFOLLOW : 0);
+    let fd = null;
+    try {
+        if (params.rejectPathSymlink) {
+            const candidateStat = ioFs.lstatSync(params.filePath);
+            if (candidateStat.isSymbolicLink()) {
+                return { ok: false, reason: "validation" };
+            }
+        }
+        const realPath = params.resolvedPath ?? ioFs.realpathSync(params.filePath);
+        const preOpenStat = ioFs.lstatSync(realPath);
+        if (!isAllowedType(preOpenStat, allowedType)) {
+            return { ok: false, reason: "validation" };
+        }
+        if (params.rejectHardlinks && preOpenStat.isFile() && preOpenStat.nlink > 1) {
+            return { ok: false, reason: "validation" };
+        }
+        if (params.maxBytes !== undefined &&
+            preOpenStat.isFile() &&
+            preOpenStat.size > params.maxBytes) {
+            return { ok: false, reason: "validation" };
+        }
+        fd = ioFs.openSync(realPath, openReadFlags);
+        const openedStat = ioFs.fstatSync(fd);
+        if (!isAllowedType(openedStat, allowedType)) {
+            return { ok: false, reason: "validation" };
+        }
+        if (params.rejectHardlinks && openedStat.isFile() && openedStat.nlink > 1) {
+            return { ok: false, reason: "validation" };
+        }
+        if (params.maxBytes !== undefined && openedStat.isFile() && openedStat.size > params.maxBytes) {
+            return { ok: false, reason: "validation" };
+        }
+        if (!sameFileIdentity(preOpenStat, openedStat)) {
+            return { ok: false, reason: "validation" };
+        }
+        const opened = { ok: true, path: realPath, fd, stat: openedStat };
+        fd = null;
+        return opened;
+    }
+    catch (error) {
+        if (isExpectedPathError(error)) {
+            return { ok: false, reason: "path", error };
+        }
+        return { ok: false, reason: "io", error };
+    }
+    finally {
+        if (fd !== null) {
+            ioFs.closeSync(fd);
+        }
+    }
+}
+function isAllowedType(stat, allowedType) {
+    if (allowedType === "directory") {
+        return stat.isDirectory();
+    }
+    return stat.isFile();
+}

package/dist/pinned-path.d.ts

@@ -0,0 +1,7 @@
+export declare function isPinnedPathHelperSpawnError(error: unknown): boolean;
+export declare function runPinnedPathHelper(params: {
+    operation: "mkdirp" | "remove";
+    rootPath: string;
+    relativePath: string;
+}): Promise<void>;
+//# sourceMappingURL=pinned-path.d.ts.map

package/dist/pinned-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-path.d.ts","sourceRoot":"","sources":["../src/pinned-path.ts"],"names":[],"mappings":"AAIA,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB"}

package/dist/pinned-path.js

@@ -0,0 +1,21 @@
+import { FsSafeError } from "./errors.js";
+import { canFallbackFromPythonError } from "./pinned-python-config.js";
+import { runPinnedHelper } from "./pinned-helper.js";
+export function isPinnedPathHelperSpawnError(error) {
+    return canFallbackFromPythonError(error);
+}
+export async function runPinnedPathHelper(params) {
+    try {
+        await runPinnedHelper(params.operation, params.rootPath, {
+            relativePath: params.relativePath,
+        });
+    }
+    catch (error) {
+        if (error instanceof FsSafeError) {
+            throw error;
+        }
+        throw new FsSafeError("helper-failed", "pinned path helper failed", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+}

package/dist/pinned-python-config.d.ts

@@ -0,0 +1,9 @@
+export type FsSafePythonMode = "auto" | "off" | "require";
+export type FsSafePythonConfig = {
+    mode: FsSafePythonMode;
+    pythonPath?: string;
+};
+export declare function configureFsSafePython(config: Partial<FsSafePythonConfig>): void;
+export declare function getFsSafePythonConfig(): FsSafePythonConfig;
+export declare function canFallbackFromPythonError(error: unknown): boolean;
+//# sourceMappingURL=pinned-python-config.d.ts.map

package/dist/pinned-python-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-python-config.d.ts","sourceRoot":"","sources":["../src/pinned-python-config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAqBF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAE/E;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAc1D;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOlE"}

package/dist/pinned-python-config.js

@@ -0,0 +1,39 @@
+let overrideConfig = {};
+function parseMode(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "0" || normalized === "false" || normalized === "off" || normalized === "never") {
+        return "off";
+    }
+    if (normalized === "1" || normalized === "true" || normalized === "on" || normalized === "auto") {
+        return "auto";
+    }
+    if (normalized === "required" || normalized === "require") {
+        return "require";
+    }
+    return undefined;
+}
+export function configureFsSafePython(config) {
+    overrideConfig = { ...overrideConfig, ...config };
+}
+export function getFsSafePythonConfig() {
+    return {
+        mode: overrideConfig.mode ??
+            parseMode(process.env.FS_SAFE_PYTHON_MODE) ??
+            parseMode(process.env.OPENCLAW_FS_SAFE_PYTHON_MODE) ??
+            "auto",
+        pythonPath: overrideConfig.pythonPath ??
+            process.env.FS_SAFE_PYTHON ??
+            process.env.OPENCLAW_FS_SAFE_PYTHON ??
+            process.env.OPENCLAW_PINNED_PYTHON ??
+            process.env.OPENCLAW_PINNED_WRITE_PYTHON,
+    };
+}
+export function canFallbackFromPythonError(error) {
+    return (getFsSafePythonConfig().mode !== "require" &&
+        error instanceof Error &&
+        "code" in error &&
+        error.code === "helper-unavailable");
+}

package/dist/pinned-python.d.ts

@@ -0,0 +1,12 @@
+type PinnedPythonOperation = "copy" | "stat" | "readdir" | "mkdirp" | "remove" | "rename" | "write";
+export declare function __resetPinnedPythonWorkerForTest(): void;
+export declare function runPinnedPythonOperation<T>(params: {
+    operation: PinnedPythonOperation;
+    rootPath: string;
+    payload: Record<string, unknown>;
+}): Promise<T>;
+export declare function assertPinnedPythonOperationAvailable(): void;
+export declare function validatePinnedOperationPayload(payload: Record<string, unknown>): void;
+export declare function isPinnedHelperUnavailable(error: unknown): boolean;
+export {};
+//# sourceMappingURL=pinned-python.d.ts.map

package/dist/pinned-python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-python.d.ts","sourceRoot":"","sources":["../src/pinned-python.ts"],"names":[],"mappings":"AAyUA,KAAK,qBAAqB,GACtB,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,CAAC;AAiBZ,wBAAgB,gCAAgC,IAAI,IAAI,CAQvD;AAiND,wBAAsB,wBAAwB,CAAC,CAAC,EAAE,MAAM,EAAE;IACxD,SAAS,EAAE,qBAAqB,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,GAAG,OAAO,CAAC,CAAC,CAAC,CA4Bb;AAED,wBAAgB,oCAAoC,IAAI,IAAI,CAK3D;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAarF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAIjE"}