@openclaw/fs-safe 0.2.0 → 0.2.2

package/dist/fs-pinned-path-helper.js

@@ -0,0 +1,182 @@
+import { spawn } from "node:child_process";
+import fsSync from "node:fs";
+import { FsSafeError } from "./errors.js";
+const LOCAL_PINNED_PATH_PYTHON = [
+    "import errno",
+    "import json",
+    "import os",
+    "import stat",
+    "import sys",
+    "",
+    "operation = sys.argv[1]",
+    "root_path = sys.argv[2]",
+    "relative_path = sys.argv[3]",
+    "",
+    "DIR_FLAGS = os.O_RDONLY",
+    "if hasattr(os, 'O_DIRECTORY'):",
+    "    DIR_FLAGS |= os.O_DIRECTORY",
+    "if hasattr(os, 'O_NOFOLLOW'):",
+    "    DIR_FLAGS |= os.O_NOFOLLOW",
+    "",
+    "def open_dir(path_value, dir_fd=None):",
+    "    return os.open(path_value, DIR_FLAGS, dir_fd=dir_fd)",
+    "",
+    "def split_segments(relative_path):",
+    "    return [part for part in relative_path.split('/') if part and part != '.']",
+    "",
+    "def validate_segment(segment):",
+    "    if segment == '..':",
+    "        raise OSError(errno.EPERM, 'path traversal is not allowed', segment)",
+    "",
+    "def walk_existing_path(root_fd, segments):",
+    "    current_fd = os.dup(root_fd)",
+    "    try:",
+    "        for segment in segments:",
+    "            validate_segment(segment)",
+    "            next_fd = open_dir(segment, dir_fd=current_fd)",
+    "            os.close(current_fd)",
+    "            current_fd = next_fd",
+    "        return current_fd",
+    "    except Exception:",
+    "        os.close(current_fd)",
+    "        raise",
+    "",
+    "def mkdirp_within_root(root_fd, segments):",
+    "    current_fd = os.dup(root_fd)",
+    "    try:",
+    "        for segment in segments:",
+    "            validate_segment(segment)",
+    "            try:",
+    "                next_fd = open_dir(segment, dir_fd=current_fd)",
+    "            except FileNotFoundError:",
+    "                os.mkdir(segment, 0o777, dir_fd=current_fd)",
+    "                next_fd = open_dir(segment, dir_fd=current_fd)",
+    "            os.close(current_fd)",
+    "            current_fd = next_fd",
+    "    finally:",
+    "        os.close(current_fd)",
+    "",
+    "def remove_within_root(root_fd, segments):",
+    "    if not segments:",
+    "        raise OSError(errno.EPERM, 'refusing to remove root path')",
+    "    parent_segments = segments[:-1]",
+    "    basename = segments[-1]",
+    "    validate_segment(basename)",
+    "    parent_fd = walk_existing_path(root_fd, parent_segments)",
+    "    try:",
+    "        target_stat = os.lstat(basename, dir_fd=parent_fd)",
+    "        if stat.S_ISDIR(target_stat.st_mode) and not stat.S_ISLNK(target_stat.st_mode):",
+    "            os.rmdir(basename, dir_fd=parent_fd)",
+    "        else:",
+    "            os.unlink(basename, dir_fd=parent_fd)",
+    "    finally:",
+    "        os.close(parent_fd)",
+    "",
+    "def emit_error(exc):",
+    "    payload = {",
+    "        'name': exc.__class__.__name__,",
+    "        'errno': getattr(exc, 'errno', None),",
+    "        'message': str(exc),",
+    "    }",
+    "    print(json.dumps(payload), file=sys.stderr)",
+    "",
+    "root_fd = None",
+    "try:",
+    "    root_fd = open_dir(root_path)",
+    "    segments = split_segments(relative_path)",
+    "    if operation == 'mkdirp':",
+    "        mkdirp_within_root(root_fd, segments)",
+    "    elif operation == 'remove':",
+    "        remove_within_root(root_fd, segments)",
+    "    else:",
+    "        raise RuntimeError(f'unknown pinned path operation: {operation}')",
+    "except Exception as exc:",
+    "    emit_error(exc)",
+    "    sys.exit(1)",
+    "finally:",
+    "    if root_fd is not None:",
+    "        os.close(root_fd)",
+].join("\n");
+const PINNED_PATH_PYTHON_CANDIDATES = [
+    process.env.OPENCLAW_PINNED_PYTHON,
+    // Keep the write-specific alias for backwards compatibility.
+    process.env.OPENCLAW_PINNED_WRITE_PYTHON,
+    "/usr/bin/python3",
+    "/opt/homebrew/bin/python3",
+    "/usr/local/bin/python3",
+].filter((value) => Boolean(value));
+let cachedPinnedPathPython = "";
+function canExecute(binPath) {
+    try {
+        fsSync.accessSync(binPath, fsSync.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolvePinnedPathPython() {
+    if (cachedPinnedPathPython) {
+        return cachedPinnedPathPython;
+    }
+    for (const candidate of PINNED_PATH_PYTHON_CANDIDATES) {
+        if (canExecute(candidate)) {
+            cachedPinnedPathPython = candidate;
+            return cachedPinnedPathPython;
+        }
+    }
+    cachedPinnedPathPython = "python3";
+    return cachedPinnedPathPython;
+}
+function buildPinnedPathError(stderr, code, signal) {
+    const trimmed = stderr.trim();
+    if (trimmed.startsWith("{")) {
+        try {
+            const payload = JSON.parse(trimmed);
+            if (payload.errno === 2) {
+                return new FsSafeError("not-found", "file not found");
+            }
+            if (payload.errno === 20 || payload.errno === 40) {
+                return new FsSafeError("path-alias", "path is not under root");
+            }
+            if (payload.errno === 39) {
+                return new FsSafeError("not-empty", "directory is not empty");
+            }
+            if (payload.errno === 1 || payload.errno === 13 || payload.errno === 21) {
+                return new FsSafeError("not-removable", "path is not removable under root");
+            }
+            return new FsSafeError("helper-failed", payload.message || "pinned path helper failed");
+        }
+        catch {
+            // Fall through to the generic helper failure below.
+        }
+    }
+    return new FsSafeError("helper-failed", trimmed || `Pinned path helper failed with code ${code ?? "null"} (${signal ?? "?"})`);
+}
+export function isPinnedPathHelperSpawnError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const maybeErrno = error;
+    if (typeof maybeErrno.syscall !== "string" || !maybeErrno.syscall.startsWith("spawn")) {
+        return false;
+    }
+    return ["EACCES", "ENOENT", "ENOEXEC"].includes(maybeErrno.code ?? "");
+}
+export async function runPinnedPathHelper(params) {
+    const child = spawn(resolvePinnedPathPython(), ["-c", LOCAL_PINNED_PATH_PYTHON, params.operation, params.rootPath, params.relativePath], {
+        stdio: ["ignore", "ignore", "pipe"],
+    });
+    let stderr = "";
+    child.stderr.setEncoding?.("utf8");
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+    });
+    const [code, signal] = await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", (exitCode, exitSignal) => resolve([exitCode, exitSignal]));
+    });
+    if (code !== 0) {
+        throw buildPinnedPathError(stderr, code, signal);
+    }
+}

package/dist/fs-pinned-write-helper.d.ts

@@ -0,0 +1,21 @@
+import type { Readable } from "node:stream";
+import type { FileIdentityStat } from "./file-identity.js";
+type PinnedWriteInput = {
+    kind: "buffer";
+    data: string | Buffer;
+    encoding?: BufferEncoding;
+} | {
+    kind: "stream";
+    stream: Readable;
+};
+export declare function runPinnedWriteHelper(params: {
+    rootPath: string;
+    relativeParentPath: string;
+    basename: string;
+    mkdir: boolean;
+    mode: number;
+    overwrite?: boolean;
+    input: PinnedWriteInput;
+}): Promise<FileIdentityStat>;
+export {};
+//# sourceMappingURL=fs-pinned-write-helper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fs-pinned-write-helper.d.ts","sourceRoot":"","sources":["../src/fs-pinned-write-helper.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,KAAK,gBAAgB,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAoJzC,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,gBAAgB,CAAC;CACzB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgE5B"}

package/dist/fs-pinned-write-helper.js

@@ -0,0 +1,263 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+const LOCAL_PINNED_WRITE_PYTHON = [
+    "import errno",
+    "import os",
+    "import secrets",
+    "import stat",
+    "import sys",
+    "",
+    "root_path = sys.argv[1]",
+    "relative_parent = sys.argv[2]",
+    "basename = sys.argv[3]",
+    'mkdir_enabled = sys.argv[4] == "1"',
+    "file_mode = int(sys.argv[5], 8)",
+    'overwrite_enabled = sys.argv[6] == "1"',
+    "",
+    "DIR_FLAGS = os.O_RDONLY",
+    "if hasattr(os, 'O_DIRECTORY'):",
+    "    DIR_FLAGS |= os.O_DIRECTORY",
+    "if hasattr(os, 'O_NOFOLLOW'):",
+    "    DIR_FLAGS |= os.O_NOFOLLOW",
+    "",
+    "WRITE_FLAGS = os.O_WRONLY | os.O_CREAT | os.O_EXCL",
+    "if hasattr(os, 'O_NOFOLLOW'):",
+    "    WRITE_FLAGS |= os.O_NOFOLLOW",
+    "",
+    "def open_dir(path_value, dir_fd=None):",
+    "    return os.open(path_value, DIR_FLAGS, dir_fd=dir_fd)",
+    "",
+    "def walk_parent(root_fd, rel_parent, mkdir_enabled):",
+    "    current_fd = os.dup(root_fd)",
+    "    try:",
+    "        for segment in [part for part in rel_parent.split('/') if part and part != '.']:",
+    "            if segment == '..':",
+    "                raise OSError(errno.EPERM, 'path traversal is not allowed', segment)",
+    "            try:",
+    "                next_fd = open_dir(segment, dir_fd=current_fd)",
+    "            except FileNotFoundError:",
+    "                if not mkdir_enabled:",
+    "                    raise",
+    "                os.mkdir(segment, 0o777, dir_fd=current_fd)",
+    "                next_fd = open_dir(segment, dir_fd=current_fd)",
+    "            os.close(current_fd)",
+    "            current_fd = next_fd",
+    "        return current_fd",
+    "    except Exception:",
+    "        os.close(current_fd)",
+    "        raise",
+    "",
+    "def create_temp_file(parent_fd, basename, mode):",
+    "    prefix = '.' + basename + '.'",
+    "    for _ in range(128):",
+    "        candidate = prefix + secrets.token_hex(6) + '.tmp'",
+    "        try:",
+    "            fd = os.open(candidate, WRITE_FLAGS, mode, dir_fd=parent_fd)",
+    "            return candidate, fd",
+    "        except FileExistsError:",
+    "            continue",
+    "    raise RuntimeError('failed to allocate pinned temp file')",
+    "",
+    "root_fd = open_dir(root_path)",
+    "parent_fd = None",
+    "temp_fd = None",
+    "temp_name = None",
+    "try:",
+    "    parent_fd = walk_parent(root_fd, relative_parent, mkdir_enabled)",
+    "    temp_name, temp_fd = create_temp_file(parent_fd, basename, file_mode)",
+    "    while True:",
+    "        chunk = sys.stdin.buffer.read(65536)",
+    "        if not chunk:",
+    "            break",
+    "        os.write(temp_fd, chunk)",
+    "    os.fsync(temp_fd)",
+    "    os.close(temp_fd)",
+    "    temp_fd = None",
+    "    if overwrite_enabled:",
+    "        os.replace(temp_name, basename, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)",
+    "        temp_name = None",
+    "    else:",
+    "        os.link(temp_name, basename, src_dir_fd=parent_fd, dst_dir_fd=parent_fd, follow_symlinks=False)",
+    "        os.unlink(temp_name, dir_fd=parent_fd)",
+    "        temp_name = None",
+    "    os.fsync(parent_fd)",
+    "    result_stat = os.stat(basename, dir_fd=parent_fd, follow_symlinks=False)",
+    "    print(f'{result_stat.st_dev}|{result_stat.st_ino}')",
+    "finally:",
+    "    if temp_fd is not None:",
+    "        os.close(temp_fd)",
+    "    if temp_name is not None and parent_fd is not None:",
+    "        try:",
+    "            os.unlink(temp_name, dir_fd=parent_fd)",
+    "        except FileNotFoundError:",
+    "            pass",
+    "    if parent_fd is not None:",
+    "        os.close(parent_fd)",
+    "    os.close(root_fd)",
+].join("\n");
+const PINNED_WRITE_PYTHON_CANDIDATES = [
+    process.env.OPENCLAW_PINNED_WRITE_PYTHON,
+    "/usr/bin/python3",
+    "/opt/homebrew/bin/python3",
+    "/usr/local/bin/python3",
+].filter((value) => Boolean(value));
+let cachedPinnedWritePython = "";
+function canExecute(binPath) {
+    try {
+        fsSync.accessSync(binPath, fsSync.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolvePinnedWritePython() {
+    if (cachedPinnedWritePython) {
+        return cachedPinnedWritePython;
+    }
+    for (const candidate of PINNED_WRITE_PYTHON_CANDIDATES) {
+        if (canExecute(candidate)) {
+            cachedPinnedWritePython = candidate;
+            return cachedPinnedWritePython;
+        }
+    }
+    cachedPinnedWritePython = "python3";
+    return cachedPinnedWritePython;
+}
+function parsePinnedIdentity(stdout) {
+    const line = stdout
+        .trim()
+        .split(/\r?\n/)
+        .map((value) => value.trim())
+        .findLast(Boolean);
+    if (!line) {
+        throw new Error("Pinned write helper returned no identity");
+    }
+    const [devRaw, inoRaw] = line.split("|");
+    const dev = Number.parseInt(devRaw ?? "", 10);
+    const ino = Number.parseInt(inoRaw ?? "", 10);
+    if (!Number.isFinite(dev) || !Number.isFinite(ino)) {
+        throw new Error(`Pinned write helper returned invalid identity: ${line}`);
+    }
+    return { dev, ino };
+}
+export async function runPinnedWriteHelper(params) {
+    const child = spawn(resolvePinnedWritePython(), [
+        "-c",
+        LOCAL_PINNED_WRITE_PYTHON,
+        params.rootPath,
+        params.relativeParentPath,
+        params.basename,
+        params.mkdir ? "1" : "0",
+        (params.mode || 0o600).toString(8),
+        params.overwrite === false ? "0" : "1",
+    ], {
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding?.("utf8");
+    child.stderr.setEncoding?.("utf8");
+    child.stdout.on("data", (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+    });
+    const exitPromise = once(child, "close");
+    try {
+        if (!child.stdin) {
+            const identity = await runPinnedWriteFallback(params);
+            await exitPromise.catch(() => { });
+            return identity;
+        }
+        if (params.input.kind === "buffer") {
+            const input = params.input;
+            await new Promise((resolve, reject) => {
+                child.stdin.once("error", reject);
+                if (typeof input.data === "string") {
+                    child.stdin.end(input.data, input.encoding ?? "utf8", () => resolve());
+                    return;
+                }
+                child.stdin.end(input.data, () => resolve());
+            });
+        }
+        else {
+            await pipeline(params.input.stream, child.stdin);
+        }
+        const [code, signal] = await exitPromise;
+        if (code !== 0) {
+            throw new Error(stderr.trim() ||
+                `Pinned write helper failed with code ${code ?? "null"} (${signal ?? "?"})`);
+        }
+        return parsePinnedIdentity(stdout);
+    }
+    catch (error) {
+        child.kill("SIGKILL");
+        await exitPromise.catch(() => { });
+        throw error;
+    }
+}
+async function runPinnedWriteFallback(params) {
+    const parentPath = params.relativeParentPath
+        ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
+        : params.rootPath;
+    if (params.mkdir) {
+        await fs.mkdir(parentPath, { recursive: true });
+    }
+    const targetPath = path.join(parentPath, params.basename);
+    if (params.overwrite === false) {
+        const handle = await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, params.mode);
+        let created = true;
+        try {
+            if (params.input.kind === "buffer") {
+                if (typeof params.input.data === "string") {
+                    await handle.writeFile(params.input.data, params.input.encoding ?? "utf8");
+                }
+                else {
+                    await handle.writeFile(params.input.data);
+                }
+            }
+            else {
+                await pipeline(params.input.stream, handle.createWriteStream());
+            }
+            const stat = await handle.stat();
+            created = false;
+            return { dev: stat.dev, ino: stat.ino };
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+            if (created) {
+                await fs.rm(targetPath, { force: true }).catch(() => undefined);
+            }
+        }
+    }
+    const tempPath = path.join(parentPath, `.${params.basename}.fallback.tmp`);
+    if (params.input.kind === "buffer") {
+        if (typeof params.input.data === "string") {
+            await fs.writeFile(tempPath, params.input.data, {
+                encoding: params.input.encoding ?? "utf8",
+                mode: params.mode,
+            });
+        }
+        else {
+            await fs.writeFile(tempPath, params.input.data, { mode: params.mode });
+        }
+    }
+    else {
+        const handle = await fs.open(tempPath, "w", params.mode);
+        try {
+            await pipeline(params.input.stream, handle.createWriteStream());
+        }
+        finally {
+            await handle.close().catch(() => { });
+        }
+    }
+    await fs.rename(tempPath, targetPath);
+    const stat = await fs.stat(targetPath);
+    return { dev: stat.dev, ino: stat.ino };
+}

package/dist/hardlink-guards.d.ts

@@ -0,0 +1,7 @@
+export declare function assertNoHardlinkedFinalPath(params: {
+    filePath: string;
+    root: string;
+    boundaryLabel: string;
+    allowFinalHardlinkForUnlink?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=hardlink-guards.d.ts.map

package/dist/hardlink-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hardlink-guards.d.ts","sourceRoot":"","sources":["../src/hardlink-guards.ts"],"names":[],"mappings":"AAIA,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhB"}

package/dist/hardlink-guards.js

@@ -0,0 +1,30 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import { isNotFoundPathError } from "./path-guards.js";
+export async function assertNoHardlinkedFinalPath(params) {
+    if (params.allowFinalHardlinkForUnlink) {
+        return;
+    }
+    let stat;
+    try {
+        stat = await fs.stat(params.filePath);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return;
+        }
+        throw err;
+    }
+    if (!stat.isFile()) {
+        return;
+    }
+    if (stat.nlink > 1) {
+        throw new Error(`Hardlinked path is not allowed under ${params.boundaryLabel} (${shortPath(params.root)}): ${shortPath(params.filePath)}`);
+    }
+}
+function shortPath(value) {
+    if (value.startsWith(os.homedir())) {
+        return `~${value.slice(os.homedir().length)}`;
+    }
+    return value;
+}

package/dist/home-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAeA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAsCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAWR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EACN;IACE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACD,MAAM,CAAC,UAAU,EACrB,OAAO,CAAC,EAAE,MAAM,MAAM,GACrB,MAAM,CAMR;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR"}
+{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAeA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAyCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EACN;IACE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACD,MAAM,CAAC,UAAU,EACrB,OAAO,CAAC,EAAE,MAAM,MAAM,GACrB,MAAM,CAMR;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR"}

package/dist/home-dir.js

@@ -21,17 +21,21 @@ export function resolveOsHomeDir(env = process.env, homedir = os.homedir) {
 }
 function resolveRawHomeDir(env, homedir) {
     const explicitHome = normalize(env.OPENCLAW_HOME);
-    if (explicitHome) {
-        if (explicitHome === "~" || explicitHome.startsWith("~/") || explicitHome.startsWith("~\\")) {
-            const fallbackHome = resolveRawOsHomeDir(env, homedir);
-            if (fallbackHome) {
-                return explicitHome.replace(/^~(?=$|[\\/])/, fallbackHome);
-            }
-            return undefined;
-        }
+    if (!explicitHome) {
+        return resolveRawOsHomeDir(env, homedir);
+    }
+    const segments = path.normalize(explicitHome).split(path.sep);
+    if (segments[0] !== "~") {
         return explicitHome;
     }
-    return resolveRawOsHomeDir(env, homedir);
+    // OPENCLAW_HOME starts with "~"; expand against the os home dir. Fall
+    // back to undefined when there is no os home to expand against rather
+    // than returning a raw "~"-prefixed path the caller cannot use.
+    const fallbackHome = resolveRawOsHomeDir(env, homedir);
+    if (!fallbackHome) {
+        return undefined;
+    }
+    return expandHomePrefix(explicitHome, { home: fallbackHome });
 }
 function resolveRawOsHomeDir(env, homedir) {
     const envHome = normalize(env.HOME);
@@ -59,7 +63,8 @@ export function resolveRequiredOsHomeDir(env = process.env, homedir = os.homedir
     return resolveOsHomeDir(env, homedir) ?? path.resolve(process.cwd());
 }
 export function expandHomePrefix(input, opts) {
-    if (!input.startsWith("~")) {
+    const segments = path.normalize(input).split(path.sep);
+    if (segments[0] !== "~") {
         return input;
     }
     const home = normalize(opts?.home) ??
@@ -67,22 +72,22 @@ export function expandHomePrefix(input, opts) {
     if (!home) {
         return input;
     }
-    return input.replace(/^~(?=$|[\\/])/, home);
+    return path.join(home, ...segments.slice(1));
 }
 export function resolveHomeRelativePath(input, opts) {
-    const trimmed = input.trim();
-    if (!trimmed) {
-        return trimmed;
+    if (!input) {
+        return input;
     }
-    if (trimmed.startsWith("~")) {
-        const expanded = expandHomePrefix(trimmed, {
-            home: resolveRequiredHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
-            env: opts?.env,
-            homedir: opts?.homedir,
-        });
-        return path.resolve(expanded);
+    const segments = path.normalize(input).split(path.sep);
+    if (segments[0] !== "~") {
+        return path.resolve(input);
     }
-    return path.resolve(trimmed);
+    const expanded = expandHomePrefix(input, {
+        home: resolveRequiredHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
+        env: opts?.env,
+        homedir: opts?.homedir,
+    });
+    return path.resolve(expanded);
 }
 export function resolveUserPath(input, optsOrEnv, homedir) {
     const opts = optsOrEnv && ("env" in optsOrEnv || "homedir" in optsOrEnv)
@@ -91,17 +96,17 @@ export function resolveUserPath(input, optsOrEnv, homedir) {
     return resolveHomeRelativePath(input, opts);
 }
 export function resolveOsHomeRelativePath(input, opts) {
-    const trimmed = input.trim();
-    if (!trimmed) {
-        return trimmed;
+    if (!input) {
+        return input;
     }
-    if (trimmed.startsWith("~")) {
-        const expanded = expandHomePrefix(trimmed, {
-            home: resolveRequiredOsHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
-            env: opts?.env,
-            homedir: opts?.homedir,
-        });
-        return path.resolve(expanded);
+    const segments = path.normalize(input).split(path.sep);
+    if (segments[0] !== "~") {
+        return path.resolve(input);
     }
-    return path.resolve(trimmed);
+    const expanded = expandHomePrefix(input, {
+        home: resolveRequiredOsHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
+        env: opts?.env,
+        homedir: opts?.homedir,
+    });
+    return path.resolve(expanded);
 }

package/dist/install-safe-path.d.ts

@@ -0,0 +1,20 @@
+export declare function safeDirName(input: string): string;
+export declare function safePathSegmentHashed(input: string): string;
+export declare function resolveSafeInstallDir(params: {
+    baseDir: string;
+    id: string;
+    invalidNameMessage: string;
+    nameEncoder?: (id: string) => string;
+}): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function assertCanonicalPathWithinBase(params: {
+    baseDir: string;
+    candidatePath: string;
+    boundaryLabel: string;
+}): Promise<void>;
+//# sourceMappingURL=install-safe-path.d.ts.map

package/dist/install-safe-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-safe-path.d.ts","sourceRoot":"","sources":["../src/install-safe-path.ts"],"names":[],"mappings":"AAKA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAsB3D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAe5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}