refactor(media): unify safe local file reads

src/infra/fs-safe.test.ts

@@ -0,0 +1,99 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { SafeOpenError, openFileWithinRoot, readLocalFileSafely } from "./fs-safe.js";
+
+const tempDirs: string[] = [];
+
+async function makeTempDir(prefix: string): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+describe("fs-safe", () => {
+  it("reads a local file safely", async () => {
+    const dir = await makeTempDir("openclaw-fs-safe-");
+    const file = path.join(dir, "payload.txt");
+    await fs.writeFile(file, "hello");
+
+    const result = await readLocalFileSafely({ filePath: file });
+    expect(result.buffer.toString("utf8")).toBe("hello");
+    expect(result.stat.size).toBe(5);
+    expect(result.realPath).toContain("payload.txt");
+  });
+
+  it("rejects directories", async () => {
+    const dir = await makeTempDir("openclaw-fs-safe-");
+    await expect(readLocalFileSafely({ filePath: dir })).rejects.toMatchObject({
+      code: "not-file",
+    });
+  });
+
+  it("enforces maxBytes", async () => {
+    const dir = await makeTempDir("openclaw-fs-safe-");
+    const file = path.join(dir, "big.bin");
+    await fs.writeFile(file, Buffer.alloc(8));
+
+    await expect(readLocalFileSafely({ filePath: file, maxBytes: 4 })).rejects.toMatchObject({
+      code: "too-large",
+    });
+  });
+
+  it.runIf(process.platform !== "win32")("rejects symlinks", async () => {
+    const dir = await makeTempDir("openclaw-fs-safe-");
+    const target = path.join(dir, "target.txt");
+    const link = path.join(dir, "link.txt");
+    await fs.writeFile(target, "target");
+    await fs.symlink(target, link);
+
+    await expect(readLocalFileSafely({ filePath: link })).rejects.toMatchObject({
+      code: "symlink",
+    });
+  });
+
+  it("blocks traversal outside root", async () => {
+    const root = await makeTempDir("openclaw-fs-safe-root-");
+    const outside = await makeTempDir("openclaw-fs-safe-outside-");
+    const file = path.join(outside, "outside.txt");
+    await fs.writeFile(file, "outside");
+
+    await expect(
+      openFileWithinRoot({
+        rootDir: root,
+        relativePath: path.join("..", path.basename(outside), "outside.txt"),
+      }),
+    ).rejects.toMatchObject({ code: "invalid-path" });
+  });
+
+  it.runIf(process.platform !== "win32")("blocks symlink escapes under root", async () => {
+    const root = await makeTempDir("openclaw-fs-safe-root-");
+    const outside = await makeTempDir("openclaw-fs-safe-outside-");
+    const target = path.join(outside, "outside.txt");
+    const link = path.join(root, "link.txt");
+    await fs.writeFile(target, "outside");
+    await fs.symlink(target, link);
+
+    await expect(
+      openFileWithinRoot({
+        rootDir: root,
+        relativePath: "link.txt",
+      }),
+    ).rejects.toMatchObject({ code: "invalid-path" });
+  });
+
+  it("returns not-found for missing files", async () => {
+    const dir = await makeTempDir("openclaw-fs-safe-");
+    const missing = path.join(dir, "missing.txt");
+
+    await expect(readLocalFileSafely({ filePath: missing })).rejects.toBeInstanceOf(SafeOpenError);
+    await expect(readLocalFileSafely({ filePath: missing })).rejects.toMatchObject({
+      code: "not-found",
+    });
+  });
+});

src/infra/fs-safe.ts

@@ -1,16 +1,22 @@
 import type { Stats } from "node:fs";
-import { constants as fsConstants } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 
-export type SafeOpenErrorCode = "invalid-path" | "not-found";
+export type SafeOpenErrorCode =
+  | "invalid-path"
+  | "not-found"
+  | "symlink"
+  | "not-file"
+  | "path-mismatch"
+  | "too-large";
 
 export class SafeOpenError extends Error {
   code: SafeOpenErrorCode;
 
-  constructor(code: SafeOpenErrorCode, message: string) {
-    super(message);
+  constructor(code: SafeOpenErrorCode, message: string, options?: ErrorOptions) {
+    super(message, options);
     this.code = code;
     this.name = "SafeOpenError";
   }
@@ -22,7 +28,15 @@ export type SafeOpenResult = {
   stat: Stats;
 };
 
+export type SafeLocalReadResult = {
+  buffer: Buffer;
+  realPath: string;
+  stat: Stats;
+};
+
 const NOT_FOUND_CODES = new Set(["ENOENT", "ENOTDIR"]);
+const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
+const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
 
 const ensureTrailingSep = (value: string) => (value.endsWith(path.sep) ? value : value + path.sep);
 
@@ -35,6 +49,51 @@ const isNotFoundError = (err: unknown) =>
 const isSymlinkOpenError = (err: unknown) =>
   isNodeError(err) && (err.code === "ELOOP" || err.code === "EINVAL" || err.code === "ENOTSUP");
 
+async function openVerifiedLocalFile(filePath: string): Promise<SafeOpenResult> {
+  let handle: FileHandle;
+  try {
+    handle = await fs.open(filePath, OPEN_READ_FLAGS);
+  } catch (err) {
+    if (isNotFoundError(err)) {
+      throw new SafeOpenError("not-found", "file not found");
+    }
+    if (isSymlinkOpenError(err)) {
+      throw new SafeOpenError("symlink", "symlink open blocked", { cause: err });
+    }
+    throw err;
+  }
+
+  try {
+    const [stat, lstat] = await Promise.all([handle.stat(), fs.lstat(filePath)]);
+    if (lstat.isSymbolicLink()) {
+      throw new SafeOpenError("symlink", "symlink not allowed");
+    }
+    if (!stat.isFile()) {
+      throw new SafeOpenError("not-file", "not a file");
+    }
+    if (stat.ino !== lstat.ino || stat.dev !== lstat.dev) {
+      throw new SafeOpenError("path-mismatch", "path changed during read");
+    }
+
+    const realPath = await fs.realpath(filePath);
+    const realStat = await fs.stat(realPath);
+    if (stat.ino !== realStat.ino || stat.dev !== realStat.dev) {
+      throw new SafeOpenError("path-mismatch", "path mismatch");
+    }
+
+    return { handle, realPath, stat };
+  } catch (err) {
+    await handle.close().catch(() => {});
+    if (err instanceof SafeOpenError) {
+      throw err;
+    }
+    if (isNotFoundError(err)) {
+      throw new SafeOpenError("not-found", "file not found");
+    }
+    throw err;
+  }
+}
+
 export async function openFileWithinRoot(params: {
   rootDir: string;
   relativePath: string;
@@ -54,52 +113,44 @@ export async function openFileWithinRoot(params: {
     throw new SafeOpenError("invalid-path", "path escapes root");
   }
 
-  const supportsNoFollow = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
-  const flags = fsConstants.O_RDONLY | (supportsNoFollow ? fsConstants.O_NOFOLLOW : 0);
-
-  let handle: FileHandle;
+  let opened: SafeOpenResult;
   try {
-    handle = await fs.open(resolved, flags);
+    opened = await openVerifiedLocalFile(resolved);
   } catch (err) {
-    if (isNotFoundError(err)) {
-      throw new SafeOpenError("not-found", "file not found");
-    }
-    if (isSymlinkOpenError(err)) {
-      throw new SafeOpenError("invalid-path", "symlink open blocked");
+    if (err instanceof SafeOpenError) {
+      if (err.code === "not-found") {
+        throw err;
+      }
+      throw new SafeOpenError("invalid-path", "path is not a regular file under root", {
+        cause: err,
+      });
     }
     throw err;
   }
 
+  if (!opened.realPath.startsWith(rootWithSep)) {
+    await opened.handle.close().catch(() => {});
+    throw new SafeOpenError("invalid-path", "path escapes root");
+  }
+
+  return opened;
+}
+
+export async function readLocalFileSafely(params: {
+  filePath: string;
+  maxBytes?: number;
+}): Promise<SafeLocalReadResult> {
+  const opened = await openVerifiedLocalFile(params.filePath);
   try {
-    const lstat = await fs.lstat(resolved).catch(() => null);
-    if (lstat?.isSymbolicLink()) {
-      throw new SafeOpenError("invalid-path", "symlink not allowed");
+    if (params.maxBytes !== undefined && opened.stat.size > params.maxBytes) {
+      throw new SafeOpenError(
+        "too-large",
+        `file exceeds limit of ${params.maxBytes} bytes (got ${opened.stat.size})`,
+      );
     }
-
-    const realPath = await fs.realpath(resolved);
-    if (!realPath.startsWith(rootWithSep)) {
-      throw new SafeOpenError("invalid-path", "path escapes root");
-    }
-
-    const stat = await handle.stat();
-    if (!stat.isFile()) {
-      throw new SafeOpenError("invalid-path", "not a file");
-    }
-
-    const realStat = await fs.stat(realPath);
-    if (stat.ino !== realStat.ino || stat.dev !== realStat.dev) {
-      throw new SafeOpenError("invalid-path", "path mismatch");
-    }
-
-    return { handle, realPath, stat };
-  } catch (err) {
-    await handle.close().catch(() => {});
-    if (err instanceof SafeOpenError) {
-      throw err;
-    }
-    if (isNotFoundError(err)) {
-      throw new SafeOpenError("not-found", "file not found");
-    }
-    throw err;
+    const buffer = await opened.handle.readFile();
+    return { buffer, realPath: opened.realPath, stat: opened.stat };
+  } finally {
+    await opened.handle.close().catch(() => {});
   }
 }