homeio

1import { lstat, mkdtemp, mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
2import os from "node:os";
3import path from "node:path";
4import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
5
6let mockDataRoot = "";
7
8vi.mock("@/lib/server/modules/files/stars-repository", () => ({
9  isPathStarredInDb: vi.fn(async () => false),
10  listStarredPathsFromDb: vi.fn(async () => []),
11  setPathStarredInDb: vi.fn(async () => undefined),
12}));
13
14vi.mock("@/lib/server/modules/files/trash-repository", () => ({
15  listTrashEntriesFromDb: vi.fn(async () => []),
16}));
17
18vi.mock("@/lib/server/modules/files/path-resolver", () => {
19  class FilesPathError extends Error {
20    code: string;
21    statusCode: number;
22
23    constructor(
24      message: string,
25      options?: {
26        code?: string;
27        statusCode?: number;
28      },
29    ) {
30      super(message);
31      this.code = options?.code ?? "internal_error";
32      this.statusCode = options?.statusCode ?? 500;
33    }
34  }
35
36  function ensureWithinRoot(rootPath: string, absolutePath: string) {
37    const relative = path.relative(rootPath, absolutePath);
38    const within =
39      relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
40    if (!within) {
41      throw new FilesPathError("Path escapes root", {
42        code: "path_outside_root",
43        statusCode: 400,
44      });
45    }
46  }
47
48  return {
49    FilesPathError,
50    resolvePathWithinFilesRoot: vi.fn(async (input: {
51      inputPath?: string;
52      allowEmpty?: boolean;
53      allowHiddenSegments?: boolean;
54      allowMissingLeaf?: boolean;
55      requiredPrefix?: string;
56    }) => {
57      const cleaned = (input.inputPath ?? "").trim().replaceAll("\\", "/");
58      if (!cleaned) {
59        if (!input.allowEmpty) {
60          throw new FilesPathError("Invalid path", {
61            code: "invalid_path",
62            statusCode: 400,
63          });
64        }
65      }
66
67      const normalized = cleaned ? path.posix.normalize(cleaned) : "";
68      if (cleaned.startsWith("/") || cleaned.includes("\0")) {
69        throw new FilesPathError("Invalid path", {
70          code: "invalid_path",
71          statusCode: 400,
72        });
73      }
74      if (normalized === ".." || normalized.startsWith("../")) {
75        throw new FilesPathError("Path escapes root", {
76          code: "path_outside_root",
77          statusCode: 400,
78        });
79      }
80
81      const relativePath = normalized === "." ? "" : normalized;
82      const segments = relativePath ? relativePath.split("/") : [];
83      if (
84        input.requiredPrefix &&
85        relativePath !== input.requiredPrefix &&
86        !relativePath.startsWith(`${input.requiredPrefix}/`)
87      ) {
88        throw new FilesPathError("Invalid path", {
89          code: "invalid_path",
90          statusCode: 400,
91        });
92      }
93      if (!input.allowHiddenSegments && segments.some((segment) => segment.startsWith("."))) {
94        throw new FilesPathError("Hidden files are not allowed", {
95          code: "hidden_blocked",
96          statusCode: 403,
97        });
98      }
99
100      let current = mockDataRoot;
101      for (const segment of segments) {
102        current = path.join(current, segment);
103        try {
104          const info = await lstat(current);
105          if (info.isSymbolicLink()) {
106            throw new FilesPathError("Symlinks are not allowed", {
107              code: "symlink_blocked",
108              statusCode: 403,
109            });
110          }
111        } catch (error) {
112          const nodeError = error as NodeJS.ErrnoException;
113          if (nodeError?.code === "ENOENT") {
114            if (input.allowMissingLeaf) break;
115            throw new FilesPathError("File or directory not found", {
116              code: "not_found",
117              statusCode: 404,
118            });
119          }
120          throw error;
121        }
122      }
123
124      const absolutePath = path.resolve(mockDataRoot, relativePath);
125      ensureWithinRoot(mockDataRoot, absolutePath);
126      try {
127        await lstat(absolutePath);
128        return {
129          rootPath: mockDataRoot,
130          relativePath,
131          absolutePath,
132          segments,
133          exists: true,
134        };
135      } catch (error) {
136        const nodeError = error as NodeJS.ErrnoException;
137        if (nodeError?.code !== "ENOENT") throw error;
138      }
139
140      if (!input.allowMissingLeaf) {
141        throw new FilesPathError("File or directory not found", {
142          code: "not_found",
143          statusCode: 404,
144        });
145      }
146
147      return {
148        rootPath: mockDataRoot,
149        relativePath,
150        absolutePath,
151        segments,
152        exists: false,
153      };
154    }),
155  };
156});
157
158import {
159  createDirectoryEntry,
160  createFileEntry,
161  MAX_TEXT_READ_BYTES,
162  listDirectory,
163  pasteEntry,
164  readFileForViewer,
165  searchFiles,
166  writeTextFile,
167} from "@/lib/server/modules/files/service";
168
169describe("files service", () => {
170  beforeEach(async () => {
171    mockDataRoot = await mkdtemp(path.join(os.tmpdir(), "home-server-files-"));
172  });
173
174  afterEach(async () => {
175    if (mockDataRoot) {
176      await rm(mockDataRoot, { recursive: true, force: true });
177    }
178  });
179
180  it("lists folders first and hides hidden and symlink entries by default", async () => {
181    await mkdir(path.join(mockDataRoot, "ZetaFolder"), { recursive: true });
182    await writeFile(path.join(mockDataRoot, "alpha.txt"), "alpha", "utf8");
183    await writeFile(path.join(mockDataRoot, ".hidden.txt"), "hidden", "utf8");
184    await symlink(path.join(mockDataRoot, "alpha.txt"), path.join(mockDataRoot, "alpha-link"));
185
186    const result = await listDirectory({
187      path: "",
188    });
189
190    expect(result.root).toBe(mockDataRoot);
191    expect(result.cwd).toBe("");
192    expect(result.entries.map((entry) => entry.name)).toEqual([
193      "ZetaFolder",
194      "alpha.txt",
195    ]);
196    expect(result.entries[0]?.type).toBe("folder");
197    expect(result.entries[1]?.type).toBe("file");
198  });
199
200  it("blocks traversal paths outside root", async () => {
201    await expect(
202      listDirectory({
203        path: "../etc",
204      }),
205    ).rejects.toMatchObject({
206      code: "path_outside_root",
207    });
208  });
209
210  it("blocks symlink traversal", async () => {
211    await mkdir(path.join(mockDataRoot, "safe"), { recursive: true });
212    await symlink(path.join(mockDataRoot, "safe"), path.join(mockDataRoot, "safe-link"));
213
214    await expect(
215      listDirectory({
216        path: "safe-link",
217      }),
218    ).rejects.toMatchObject({
219      code: "symlink_blocked",
220    });
221  });
222
223  it("classifies read mode for text, image, and pdf files", async () => {
224    await writeFile(path.join(mockDataRoot, "config.yaml"), "name: home", "utf8");
225    await writeFile(path.join(mockDataRoot, "photo.png"), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
226    await writeFile(path.join(mockDataRoot, "manual.pdf"), Buffer.from("%PDF-1.7", "utf8"));
227
228    const textResult = await readFileForViewer({
229      path: "config.yaml",
230    });
231    const imageResult = await readFileForViewer({
232      path: "photo.png",
233    });
234    const pdfResult = await readFileForViewer({
235      path: "manual.pdf",
236    });
237
238    expect(textResult.mode).toBe("text");
239    expect(textResult.content).toBe("name: home");
240    expect(imageResult.mode).toBe("image");
241    expect(imageResult.content).toBeNull();
242    expect(pdfResult.mode).toBe("pdf");
243    expect(pdfResult.content).toBeNull();
244  });
245
246  it("returns too_large mode for oversized text files", async () => {
247    const largeText = "a".repeat(MAX_TEXT_READ_BYTES + 1);
248    await writeFile(path.join(mockDataRoot, "large.txt"), largeText, "utf8");
249
250    const result = await readFileForViewer({
251      path: "large.txt",
252    });
253
254    expect(result.mode).toBe("too_large");
255    expect(result.content).toBeNull();
256    expect(result.sizeBytes).toBe(MAX_TEXT_READ_BYTES + 1);
257  });
258
259  it("writes text files and enforces optimistic mtime conflict", async () => {
260    const filePath = path.join(mockDataRoot, "notes.txt");
261    await writeFile(filePath, "before", "utf8");
262
263    const opened = await readFileForViewer({
264      path: "notes.txt",
265    });
266
267    const saved = await writeTextFile({
268      path: "notes.txt",
269      content: "after",
270      expectedMtimeMs: opened.mtimeMs,
271    });
272
273    expect(saved.path).toBe("notes.txt");
274    expect(await readFile(filePath, "utf8")).toBe("after");
275
276    await writeFile(filePath, "changed-outside", "utf8");
277
278    await expect(
279      writeTextFile({
280        path: "notes.txt",
281        content: "conflict-write",
282        expectedMtimeMs: opened.mtimeMs,
283      }),
284    ).rejects.toMatchObject({
285      code: "write_conflict",
286    });
287  });
288
289  it("shows hidden entries when listing Trash", async () => {
290    await mkdir(path.join(mockDataRoot, "Trash"), { recursive: true });
291    await writeFile(path.join(mockDataRoot, "Trash", ".env"), "x=1", "utf8");
292    await writeFile(path.join(mockDataRoot, "Trash", "notes.txt"), "hello", "utf8");
293
294    const result = await listDirectory({
295      path: "Trash",
296    });
297
298    expect(result.entries.map((entry) => entry.name)).toEqual([
299      ".env",
300      "notes.txt",
301    ]);
302  });
303
304  it("shows hidden entries when includeHidden is true", async () => {
305    await writeFile(path.join(mockDataRoot, ".env"), "x=1", "utf8");
306    await writeFile(path.join(mockDataRoot, "notes.txt"), "hello", "utf8");
307
308    const result = await listDirectory({
309      path: "",
310      includeHidden: true,
311    });
312
313    expect(result.entries.map((entry) => entry.name)).toEqual([
314      ".env",
315      "notes.txt",
316    ]);
317  });
318
319  it("creates folder and file entries in the requested directory", async () => {
320    await mkdir(path.join(mockDataRoot, "Documents"), { recursive: true });
321
322    const createdFolder = await createDirectoryEntry({
323      parentPath: "Documents",
324      name: "Projects",
325    });
326    const createdFile = await createFileEntry({
327      parentPath: "Documents",
328      name: "todo.txt",
329    });
330
331    expect(createdFolder.path).toBe("Documents/Projects");
332    expect(createdFolder.type).toBe("folder");
333    expect(createdFile.path).toBe("Documents/todo.txt");
334    expect(createdFile.type).toBe("file");
335  });
336
337  it("copies entries into destination directory", async () => {
338    await mkdir(path.join(mockDataRoot, "Documents"), { recursive: true });
339    await mkdir(path.join(mockDataRoot, "Media"), { recursive: true });
340    await writeFile(path.join(mockDataRoot, "Media", "photo.jpg"), "binary", "utf8");
341
342    const copied = await pasteEntry({
343      sourcePath: "Media/photo.jpg",
344      destinationPath: "Documents",
345      operation: "copy",
346    });
347
348    expect(copied.path).toBe("Documents/photo.jpg");
349    expect(await readFile(path.join(mockDataRoot, "Media", "photo.jpg"), "utf8")).toBe("binary");
350    expect(await readFile(path.join(mockDataRoot, "Documents", "photo.jpg"), "utf8")).toBe("binary");
351  });
352
353  it("moves entries into destination directory", async () => {
354    await mkdir(path.join(mockDataRoot, "Documents"), { recursive: true });
355    await mkdir(path.join(mockDataRoot, "Media"), { recursive: true });
356    await writeFile(path.join(mockDataRoot, "Media", "move-me.txt"), "m", "utf8");
357
358    const moved = await pasteEntry({
359      sourcePath: "Media/move-me.txt",
360      destinationPath: "Documents",
361      operation: "move",
362    });
363
364    expect(moved.path).toBe("Documents/move-me.txt");
365    await expect(
366      readFile(path.join(mockDataRoot, "Media", "move-me.txt"), "utf8"),
367    ).rejects.toMatchObject({
368      code: "ENOENT",
369    });
370    expect(await readFile(path.join(mockDataRoot, "Documents", "move-me.txt"), "utf8")).toBe("m");
371  });
372
373  it("rejects paste when destination exists", async () => {
374    await mkdir(path.join(mockDataRoot, "Documents"), { recursive: true });
375    await mkdir(path.join(mockDataRoot, "Media"), { recursive: true });
376    await writeFile(path.join(mockDataRoot, "Media", "photo.jpg"), "src", "utf8");
377    await writeFile(path.join(mockDataRoot, "Documents", "photo.jpg"), "dst", "utf8");
378
379    await expect(
380      pasteEntry({
381        sourcePath: "Media/photo.jpg",
382        destinationPath: "Documents",
383        operation: "copy",
384      }),
385    ).rejects.toMatchObject({
386      code: "destination_exists",
387    });
388  });
389
390  describe("searchFiles", () => {
391    it("returns matching entries by name", async () => {
392      await mkdir(path.join(mockDataRoot, "Documents"), { recursive: true });
393      await writeFile(path.join(mockDataRoot, "Documents", "notes.md"), "x");
394      await writeFile(path.join(mockDataRoot, "Documents", "ignore.txt"), "x");
395
396      const result = await searchFiles({ query: "notes" });
397
398      expect(result.entries.map((e) => e.name)).toEqual(["notes.md"]);
399      expect(result.truncated).toBeUndefined();
400    });
401
402    it("flags truncated when the deadline expires before walk completes", async () => {
403      await mkdir(path.join(mockDataRoot, "Deep"), { recursive: true });
404      // A few nested directories with files; the per-subdir setImmediate
405      // yield means a 0-ms deadline trips before we finish the walk.
406      for (let i = 0; i < 5; i += 1) {
407        const dir = path.join(mockDataRoot, "Deep", `level-${i}`);
408        await mkdir(dir, { recursive: true });
409        await writeFile(path.join(dir, "match-target.txt"), "x");
410      }
411
412      const result = await searchFiles({
413        query: "match-target",
414        timeoutMs: 1_000,
415      });
416      expect(result.entries.length).toBeGreaterThan(0);
417      expect(result.truncated).toBeUndefined();
418
419      const truncatedResult = await searchFiles({
420        query: "match-target",
421        timeoutMs: -1_000, // deadline already in the past — trips on first walk
422      });
423      expect(truncatedResult.truncated).toBe(true);
424    });
425  });
426});
427