@openclaw/fs-safe 0.2.3 → 0.2.4

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/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"}

package/dist/install-safe-path.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isPathInside } from "./path-guards.js";
+export function safeDirName(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    return trimmed.replaceAll("/", "__").replaceAll("\\", "__");
+}
+export function safePathSegmentHashed(input) {
+    const trimmed = input.trim();
+    const base = trimmed
+        .replaceAll(/[\\/]/g, "-")
+        .replaceAll(/[^a-zA-Z0-9._-]/g, "-")
+        .replaceAll(/-+/g, "-")
+        .replaceAll(/^-+/g, "")
+        .replaceAll(/-+$/g, "");
+    const normalized = base.length > 0 ? base : "skill";
+    const safe = normalized === "." || normalized === ".." ? "skill" : normalized;
+    const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 10);
+    if (safe !== trimmed) {
+        const prefix = safe.length > 50 ? safe.slice(0, 50) : safe;
+        return `${prefix}-${hash}`;
+    }
+    if (safe.length > 60) {
+        return `${safe.slice(0, 50)}-${hash}`;
+    }
+    return safe;
+}
+export function resolveSafeInstallDir(params) {
+    const encodedName = (params.nameEncoder ?? safeDirName)(params.id);
+    const targetDir = path.join(params.baseDir, encodedName);
+    const resolvedBase = path.resolve(params.baseDir);
+    const resolvedTarget = path.resolve(targetDir);
+    const relative = path.relative(resolvedBase, resolvedTarget);
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
+    return { ok: true, path: targetDir };
+}
+export async function assertCanonicalPathWithinBase(params) {
+    const baseDir = path.resolve(params.baseDir);
+    const candidatePath = path.resolve(params.candidatePath);
+    if (!isPathInside(baseDir, candidatePath)) {
+        throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+    }
+    const baseLstat = await fs.lstat(baseDir);
+    if (baseLstat.isSymbolicLink()) {
+        const baseStat = await fs.stat(baseDir);
+        if (!baseStat.isDirectory()) {
+            throw new Error(`Invalid ${params.boundaryLabel}: base directory must resolve to a directory`);
+        }
+    }
+    else if (!baseLstat.isDirectory()) {
+        throw new Error(`Invalid ${params.boundaryLabel}: base directory must be a directory`);
+    }
+    const baseRealPath = await fs.realpath(baseDir);
+    const validateDirectory = async (dirPath) => {
+        const resolvedDirPath = path.resolve(dirPath);
+        const dirLstat = await fs.lstat(dirPath);
+        if (dirLstat.isSymbolicLink()) {
+            if (resolvedDirPath !== baseDir) {
+                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            }
+            const dirStat = await fs.stat(dirPath);
+            if (!dirStat.isDirectory()) {
+                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            }
+        }
+        else if (!dirLstat.isDirectory()) {
+            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+        }
+        const dirRealPath = await fs.realpath(dirPath);
+        if (!isPathInside(baseRealPath, dirRealPath)) {
+            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+        }
+    };
+    try {
+        await validateDirectory(candidatePath);
+        return;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT") {
+            throw err;
+        }
+    }
+    await validateDirectory(path.dirname(candidatePath));
+}

package/dist/json-file.d.ts

@@ -0,0 +1,3 @@
+export declare function loadJsonFile<T = unknown>(pathname: string): T | undefined;
+export declare function saveJsonFile(pathname: string, data: unknown): void;
+//# sourceMappingURL=json-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-file.d.ts","sourceRoot":"","sources":["../src/json-file.ts"],"names":[],"mappings":"AAkGA,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAOzE;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,QAqB3D"}