refactor(media): unify safe local file reads

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(() => {});
   }
 }